Appearance
Errors
The API uses standard HTTP status codes. Codes in the 2xx range mean success, 4xx codes mean there is a problem with the request, and 5xx codes mean something went wrong on our side.
Each endpoint in the reference lists the error codes it can return.
Status codes
| Code | Meaning |
|---|---|
400 Bad Request | The request is invalid: a field is missing or has the wrong format, or the operation isn't allowed (for example, creating a product with a name that already exists). |
401 Unauthorized | The access token is missing, invalid, or expired. Get a new one. |
403 Forbidden | The access token is valid, but its User Token doesn't have the permission the endpoint needs. |
404 Not Found | The object doesn't exist, or it belongs to another account. |
429 Too Many Requests | You exceeded a rate limit, or your account reached its package's API usage limit. |
500 Internal Server Error | Unexpected error. Retry later; if it keeps happening, contact support. |
Error response formats
Error responses come in three formats. Check the Content-Type header of the response before parsing the body.
Validation errors
When a request body or parameter fails validation (missing required field, wrong type, malformed UUID), the API responds with 400 and an RFC 9457 problem details object, with Content-Type: application/problem+json. errors maps each invalid field to its messages:
json
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"instance": "/v1/licenses/license/validate",
"errors": {
"$.licenseKey": ["The input was not valid."]
}
}Error messages
Other 400 errors, and some 404 errors, return a short plain-text message that describes the problem, with Content-Type: text/plain. For example:
License not found.Messages are meant for developers and logs. Don't build logic on their exact wording, which can change; use the status code instead.
Empty responses
401, 403, 500, and most 404 responses have an empty body. Exceptions:
- When your account's subscription is inactive,
401responses have the plain-text bodyInvalid license.. - When your account reaches its package's API usage limit,
429responses have the JSON string body"Too Many Requests (Reached license limit)".429responses caused by rate limits have an empty body.
License validation
POST /v1/licenses/license/validate is an exception: when a license exists but isn't valid, it returns 400 with the full license object, and its valid field says why (INVALID or LIMITED). Always check valid rather than the status code alone.