API documentation

Everything you need to integrate with the Gini v2 Third-Party API.

Getting started API reference Store API Finance API Settings API Insights API Wholesale API Resources

MCP server Endpoint summary Error responses Rate limiting Changelog

Resources

Error responses

The API uses conventional HTTP status codes and returns a JSON body describing the problem. A 2xx status means success, 4xx means the request was rejected, and 5xx means something failed on our side.

Error shapes

Authentication failures and a few read lookups return an error key; validation and most controller errors return a message key (validation errors also include a field-keyed errors object).

Authentication or read error

{
    "error": "Invalid signature"
}

Validation error (422)

{
    "message": "The given data was invalid.",
    "errors": {
        "price": [
            "The price must be at least the configured minimum."
        ]
    }
}

Status codes

Code	Meaning
200 OK	The request succeeded.
201 Created	A resource was created (create endpoints).
202 Accepted	An async job was queued (exports).
400 Bad Request	A malformed request or an illegal order status transition.
401 Unauthorized	Missing, expired, or invalid signature or API key.
403 Forbidden	The API account is inactive. An HTML page instead of JSON means the edge blocked the request before it reached the API — see Troubleshooting.
404 Not Found	The resource does not exist or does not belong to you.
409 Conflict	A retry arrived while the first request with the same Idempotency-Key was still running.
422 Unprocessable	Validation failed or a business rule blocked the action.
429 Too Many Requests	You exceeded the rate limit — see Rate limiting.
500 Server Error	An unexpected error on our side.

Notes

Never surface raw error text to end users — map status codes to your own messages.
A 401 usually means a signing mistake: check the path has no query string, the body matches exactly, and the timestamp is within 300 seconds.
A 404 on a resource you own almost always means the identifier belongs to another merchant — the API is strictly tenant-scoped.
Tenant-scoped means every list and lookup is filtered to your own account — you can never read or mutate another merchant's data.

Previous Endpoint summary Next Rate limiting