Error Responses ¶

Understanding and handling API errors effectively.

In plain terms

When something goes wrong, the API returns a consistent JSON envelope with success: false, a human-readable message, and an errors array listing error codes and descriptions. Use the error code to decide what to do (e.g., prompt for a new API key, show a "low credits" message, or retry later).

Standard Response Envelope¶

All API responses (success and error) use the same envelope format.

Success (`2xx`)¶

{
  "data": { ... },
  "success": true,
  "message": "OK"
}

Error (`4xx` / `5xx`)¶

{
  "data": null,
  "success": false,
  "message": "Human-readable summary of the error",
  "errors": [
    { "error_code": ["Detailed error message"] }
  ]
}

Field	Type	Description
`data`	object \| null	Response payload on success; `null` on error
`success`	boolean	`true` for 2xx, `false` for 4xx/5xx
`message`	string	`"OK"` on success; human-readable error summary on failure
`errors`	array	Error-only. Each entry maps an error code to its messages

Breaking change from previous format

The previous flat error format ({ "error": "...", "message": "..." }) has been replaced by this envelope. All endpoints now return the envelope structure. Update your error-handling code to read success, message, and errors instead of the old error field.

HTTP Status Codes¶

Status	Error Code	Description	In Plain Terms
400	`insufficient_frames`	Not enough frames provided	You sent fewer frames than the model requires. Frame count must meet the model minimum (e.g. 10 for mixed-10-v2, 30 for mixed-30-v2).
400	`missing_field`	Required field missing	A required field (e.g. `session_id`, `frames`) is missing from the request.
401	`invalid_key`	Invalid or missing API key	Your API key is wrong, expired, or not sent. Check the `X-API-Key` header.
402	`insufficient_credits`	Not enough credits	Your account has run out of credits. Top up in the Developer Portal.
402	`account_suspended`	Account suspended	Your account is suspended due to a payment issue. Update your payment method in the Developer Portal.
403	`insufficient_scope`	API key lacks required scope	Your API key does not have permission for this operation. Create a key with the required scope in the Developer Portal.
400	`validation_error`	Request validation failed	The request format is invalid (e.g. wrong field types, invalid UUID). Returned as `400` with field-level detail in `errors` (not `422`).
429	`rate_limit_exceeded`	Too many requests	You've hit the request limit. Wait for `retry_after` seconds and try again.
500	`internal_error`	Server error	Something went wrong on our side. Retry later or check the Status Page.

Common Errors¶

Insufficient Frames (400)¶

Returned when the number of submitted frames is less than the required minimum for the endpoint.

{
  "data": null,
  "success": false,
  "message": "Insufficient frames. Model \"10\" requires 10 frames, received 5.",
  "errors": [
    { "insufficient_frames": ["Insufficient frames. Model \"10\" requires 10 frames, received 5."] }
  ]
}

Invalid API Key (401)¶

Returned when the API key is invalid or missing.

{
  "data": null,
  "success": false,
  "message": "Not authenticated",
  "errors": [
    { "invalid_key": ["Not authenticated"] }
  ]
}

Insufficient Credits (402)¶

Returned when your account doesn't have enough credits to process the request.

{
  "data": null,
  "success": false,
  "message": "Insufficient credits. Required: 1, available: 0",
  "errors": [
    { "insufficient_credits": ["Insufficient credits. Required: 1, available: 0"] }
  ]
}

Account Suspended (402)¶

Returned when your account is suspended due to a payment issue (e.g. failed payment, overdue invoice).

{
  "data": null,
  "success": false,
  "message": "Your account is suspended due to a payment issue. Please update your payment method.",
  "errors": [
    { "account_suspended": ["Your account is suspended due to a payment issue. Please update your payment method."] }
  ]
}

Validation Error (400)¶

Returned when the request body fails validation. The API converts 422 validation errors to 400 with field-level detail.

{
  "data": null,
  "success": false,
  "message": "session_id is required",
  "errors": [
    { "session_id": ["session_id is required"] }
  ]
}

Insufficient Scope (403)¶

Returned when your API key does not have the required scope for the requested endpoint.

{
  "data": null,
  "success": false,
  "message": "API key lacks required scope: detection:write",
  "errors": [
    { "insufficient_scope": ["API key lacks required scope: detection:write"] }
  ]
}

Rate Limit Exceeded (429)¶

Returned when you've exceeded the rate limit for your account.

{
  "data": null,
  "success": false,
  "message": "Rate limit exceeded. Please try again later.",
  "errors": [
    { "rate_limit_exceeded": ["Rate limit exceeded. Please try again later."] }
  ]
}

Handling Errors¶

Check success first — if false, the request failed
Read message for a human-readable summary
Iterate errors to find specific error codes (e.g. insufficient_frames, invalid_key)
Use the error code to decide your recovery action
For insufficient_scope, create a new API key with the required scope in the Developer Portal
For rate limits, implement exponential backoff
Implement retry logic for transient errors (500)
For persistent 500 errors, check our Status Page for ongoing incidents

Error Responses¶