Errors
Status codes and the error object.
Errors use standard HTTP status codes and one JSON shape:
{
"error": {
"code": "SCOPE_DENIED",
"message": "This API key is not allowed to: edit library (scope library:write). An organisation admin can grant it in Settings → Organisation → API keys.",
"details": {}
}
}message is written to be shown to a person. Branch your code on code, not on message.
Every response, error or not, carries an x-request-id header. Quote it when you contact support. You can also send
your own x-request-id (8–64 letters, digits, - or _) and Ingenee will use it.
| Status | code | Meaning |
|---|---|---|
| 400 | VALIDATION | The body isn't valid JSON, or a parameter is malformed |
| 401 | UNAUTHENTICATED | Missing, invalid, revoked or expired key, or its creator has lost access |
| 403 | SCOPE_DENIED | The key doesn't have the scope this endpoint needs |
| 403 | FORBIDDEN | The key's role is too low for this action, for example a viewer key writing |
| 403 | MODULE_NOT_ENABLED | The organisation's plan doesn't include this module |
| 403 | ORG_SUSPENDED / ORG_CANCELED | The organisation isn't active |
| 404 | NOT_FOUND | No such resource in this organisation, or no such endpoint |
| 409 | CONFLICT | The change conflicts with current state, for example editing a field a person has locked |
| 409 | INSUFFICIENT_CREDITS | A Studio operation needs more media credits than the organisation has |
| 413 | TOO_LARGE | The request body or media file is over the limit |
| 422 | VALIDATION and others | The body is well-formed but not acceptable; message says why |
| 429 | RATE_LIMITED | Too many requests. Wait for the number of seconds in Retry-After |
| 5xx | INTERNAL | Something failed on Ingenee's side. Retry with backoff |
Some endpoints return more specific codes, such as CATALOG_REQUIRED when an upload has no catalog. The reference
lists them where they apply.