Core concepts

Errors

Errors use conventional HTTP status codes and one JSON shape with a stable code you can branch on.

Error shape

402 Payment Required

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "This request costs 46 credits; 12 are available.",
    "request_id": "req_6c250b68f1a042ca8ea4fd4c469dc3b4",
    "details": {
      "required": 46,
      "available": 12
    }
  }
}

code — stable; branch on it.
message — human-readable; may change; don’t parse it.
request_id — also in the X-Request-Id header on every response. Include it when contacting support.
details — optional structured context (e.g. validation issues as [{ path, message }], limits, allowed values).

Error codes

HTTP	Code	Meaning	What to do
400	`VALIDATION_ERROR`	Invalid body, parameter or option for the model.	Fix the request; see `details`.
400	`IDEMPOTENCY_KEY_REQUIRED`	Write request without an Idempotency-Key.	Add the header.
401	`UNAUTHORIZED`	Missing, malformed, unknown or revoked key.	Check the key.
402	`INSUFFICIENT_CREDITS`	Balance below the price.	Top up; `details.required`/`available`.
402	`SPEND_CAP_REACHED`	The key’s monthly credit limit would be exceeded.	Raise the limit or wait for next month.
403	`PLAN_REQUIRED`	Paying account is not on Influencer or Agency.	Upgrade the plan.
403	`SCOPE_REQUIRED`	The key lacks the scope for this endpoint.	Use a key with that scope.
403	`ACCOUNT_SUSPENDED`	The account is suspended.	Contact support.
403	`LIMIT_REACHED`	A plan quantity limit (keys, webhooks, characters, products).	Delete something or upgrade.
404	`NOT_FOUND`	Unknown ID, another account’s resource, or unknown endpoint.	Check the ID/path.
409	`CONFLICT`	Wrong state, e.g. cancelling a processing generation.	Re-read the resource.
409	`IDEMPOTENCY_CONFLICT`	Key reused with a different request.	Use a new key.
409	`IDEMPOTENCY_IN_PROGRESS`	The first request with this key is still running.	Retry in a few seconds.
409	`SOCIAL_ACCOUNT_REQUIRED`	The platform is not connected for the character.	Create a connect link.
422	`CONTENT_BLOCKED`	The content is not allowed. Nothing is charged.	Change the prompt or media.
429	`RATE_LIMITED`	Too many requests for the key.	Wait `Retry-After` seconds.
429	`CONCURRENCY_LIMIT`	Too many jobs running for the account.	Wait for one to finish.
502	`PROVIDER_ERROR`	An upstream model failed.	Retry later with the same key.
504	`TIMEOUT`	An upstream step timed out.	Retry with the same key.
500	`INTERNAL_ERROR`	Unexpected error on our side.	Retry with the same key; contact support with the request_id if it persists.

A request can be accepted (202) and the generation fail later. Then the generation has status: "failed", an error.code (CONTENT_BLOCKED, PROVIDER_ERROR, TIMEOUT, RATE_LIMIT, VALIDATION_ERROR, INSUFFICIENT_CREDITS or UNKNOWN) and the credits back in refunded_credits. The timeline shows which stage failed.

Getting help

Email support@oriorai.com with the subject “API”, the request_id and, for generations, the gen_ ID.

Errors

Error shape

Error codes

Generation failures

Getting help