API errors and status codes - Omnichar Docs

Errors share one shape, whatever went wrong:

{
  "error": {
    "code": "licensee_not_found",
    "message": "No team or account matches that licensee.",
    "request_id": "9c1e6a2b-..."
  }
}

Branch on code, not on message: messages are written for people and can change. Include request_id when you contact us about a failed call. The same id comes back in the x-request-id response header, and if you send your own x-request-id, it is used instead. Older responses also carry the same value as requestId.

Code	Status	Meaning
`bad_request`	400	The request could not be read.
`unauthorized`	401	No key, or the key is unknown, revoked or past its rotation window.
`forbidden`	403	The key lacks the scope, your team lacks the role (for example, issuing licenses), or API access is off for the team.
`not_found`	404	No such character, license or route in this environment.
`licensee_not_found`	404	No team matches the licensee id or slug you named. An unknown email is not an error: see Licenses.
`conflict`	409	The state does not allow it yet: retraining while building, licensing a character that is not ready, a test event from a live key, or an idempotent request still in progress.
`unprocessable`	422	The body failed validation, or an `Idempotency-Key` was reused with a different body.
`storage_limit_reached`	409	An upload would take your team over its storage allowance.
`rate_limited`	429	Too many requests. See Rate limits.
`insufficient_credits`	402	No builds left and not enough credits for a production build.
`upstream_unavailable`	503	A dependency is down, or a feature is not switched on yet. Try again later.
`internal`	500	Something failed on our side.

A 5xx is safe to retry with the same Idempotency-Key; see Safe retries.

License checks

A run or download with a licensed character that the license does not cover answers 403 with the code forbidden and the reason in details:

{
  "error": {
    "code": "forbidden",
    "message": "The license does not allow this territory.",
    "details": { "reason": "territory_not_allowed", "char_id": "7f1c...", "license_key": "lic_live_..." },
    "request_id": "..."
  }
}

`details.reason`	When
`no_license`	Your team has no license for this character in this environment.
`license_pending`	The license’s `starts_at` is still ahead.
`license_revoked`	The provider revoked the license.
`license_expired`	`ends_at` has passed.
`signature_invalid`	The license on record does not match its signature. Contact us.
`media_not_allowed`	The run makes an output type that is not in `scope.media`.
`use_not_allowed`	`license_context.use` is not the license’s `scope.use`.
`territory_not_allowed`	`license_context.territory` is not in `scope.territories`.
`surface_not_allowed`	`scope.allow_list` names other surfaces or other teams.
`limit_reached`	The license has used all of `scope.max_generations`.

A blocked run never holds or charges credits. A run that was accepted and then blocked when it left the queue, because the license changed while it waited, fails with the same reason and is not charged either. A run with a licensed character and no license_context answers 400 with the code bad_request.