API Reference
Integration Guides

Errors

Handle validation, auth, rate limit, quota, and async job failures in a predictable way.

Error envelope

Most API failures come back in the standard { success, data, error }envelope. Handle error.code first, then use the message for logs or UI.

Validation error examplejson
{
  "success": false,
  "data": null,
  "error": {
    "code": "invalid_request",
    "message": "The 'prompt' parameter is required",
    "details": {
      "param": "prompt",
      "type": "missing_required_field"
    }
  }
}

What the main status codes mean

  • 400: malformed input, invalid fields, or unsafe webhook URL.
  • 401: missing or invalid bearer credential.
  • 402: API call allowance exhausted or spend cap blocked a billable job.
  • 403: valid credential, but missing required scope or disallowed auth context.
  • 404: resource not found or not owned by the caller.
  • 429: service-level rate limiting.
  • 500: internal failure or provider-side terminal failure path.

Common codes you should branch on

Allowance exhaustedjson
{
  "success": false,
  "data": null,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "API call limit reached"
  }
}
Concurrency guardjson
{
  "success": false,
  "data": null,
  "error": {
    "code": "CONCURRENT_GENERATION_LIMIT",
    "message": "Too many active generation jobs for this user.",
    "active_requests": 1,
    "concurrency_limit": 1
  }
}
Auth and scope

Expect codes like FORBIDDEN, INVALID_URL, INVALID_EVENTS, or route-specific validation failures.

Quota and spend controls

Billable jobs can fail with INSUFFICIENT_CREDITS or SPENDING_LIMIT_EXCEEDED.

Retry guidance

  • Retry 429 with backoff and honor Retry-After.
  • Retry network failures and some 5xx errors with idempotency on POST routes.
  • Do not retry 400, 401, 403, or 404 until you change input or credentials.
  • For 402, reset allowance, upgrade plan, or reduce billable calls before retrying.

POST safety

For generation endpoints, always send an Idempotency-Key when your own client may retry the same request.
Was this page helpful?
Previous
Music EndpointsNext