Errors - Reflections Talent API

An error means the request could not be evaluated at all. Every error is an RFC 9457 problem detail, sent as application/problem+json, with a stable code you can branch on.

A decision is never an error. deny and escalate are 200 responses that carry a decision, reasons and sometimes a remedy. Their codes are listed in Reason codes.

The problem format

{
  "type": "https://docs.reflections.ai/errors/parameter_invalid",
  "title": "A parameter is invalid",
  "status": 400,
  "code": "parameter_invalid",
  "param": "use.territories[1]",
  "detail": "\"UK\" is not an ISO 3166-1 alpha-2 code. Use \"GB\".",
  "request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}

Field	Always present	Meaning
`type`	Yes	A URL for this error, `https://docs.reflections.ai/errors/<code>`, which opens the code’s entry below.
`title`	Yes	A short summary. It can change; do not match on it.
`status`	Yes	The HTTP status, repeated.
`code`	Yes	The stable error code. Branch on this.
`request_id`	Yes	The same value as the `Request-Id` header. Include it when you contact support.
`detail`	No	What went wrong in this request. Log it; do not show it to end users.
`param`	No	The field at fault, as a path such as `use.territories[1]`.
`doc_url`	No	A link to the documentation for this error.

The OAuth endpoints are the exception: their 400 and 401 responses use the format their RFCs define, such as {"error": "invalid_grant", "error_description": "…"}, so OAuth libraries can read them. Each endpoint lists its error values. Their 429 and 5xx responses are problem details.

Handling errors

Branch on code, then on status. Treat an unknown code by its status.
Retry only the codes marked below, and always with the same Idempotency-Key. A new key on an unknown outcome can run the request twice. See Idempotency.
When an error stops a check, do not generate a named talent. When it stops a generation, do not deliver the output. See Failure modes.

Error codes

400 Bad request

Code	Meaning	What to do
`invalid_request`	The body is not valid JSON, or its shape is wrong.	Fix the request. Do not retry as is.
`parameter_missing`	A required field is absent. `param` names it.	Add the field.
`parameter_invalid`	A field has an invalid value. `param` names it.	Fix the value; `detail` says what is accepted.
`unsupported_modality`	The modality is not offered for this use, such as a session for `image`.	Use a supported modality or endpoint.
`unsupported_media_type`	The file type is not accepted for this purpose.	Convert the file, or use the right `purpose`.
`media_unreadable`	A file or inline media could not be decoded.	Check the bytes and `media_type`, then send again.
`version_unsupported`	`Reflections-Version` names an unknown version.	Send a version listed in Versioning.
`authorization_code_invalid`	An OAuth authorization code is unknown, expired or used, or its `code_verifier` or `redirect_uri` does not match.	Send the licensee through the authorization page again.

401 Unauthorized

Code	Meaning	What to do
`authentication_required`	No credentials were sent.	Send `Authorization: Bearer rk_…`.
`invalid_api_key`	The key is unknown or revoked.	Use a current key from the dashboard.
`token_invalid`	An authorization or session token failed verification: its signature, `aud` or `exp`.	Run a new check, or renew the session.

403 Forbidden

Code	Meaning	What to do
`insufficient_scope`	A restricted key lacks the scope this call needs. `detail` names it.	Add the scope to the key. See Authentication.
`account_not_connected`	`Reflections-Account` names an account with no active connection to yours, or the connection’s scopes do not cover this call.	Ask the licensee to connect your platform. Stop sending calls for them.
`mandate_required`	A talent-side call names a talent your account holds no active mandate for, or the mandate lacks the power the call needs. `detail` names the power.	Ask the talent to add the power in the Talent Portal. Stop acting for a talent whose mandate ended.
`livemode_mismatch`	A test object was used with a live key, or a live object with a test key.	Use the key for the object’s mode.
`live_not_activated`	A live check or generation was sent before Reflections activated live signing. Nothing was evaluated or reserved.	Do not retry: the answer stays the same until activation. Use a test key, and contact support for activation.
`platform_not_permitted`	The request names a `license` explicitly, and that license excludes your platform.	Omit `license` so the check chooses one, or ask the licensee to add your platform.

platform_not_permitted applies only when you name a license. Without one, the check is decided instead: when no license the licensee holds covers the talent on your platform, the result is a 200 with decision: "deny" and the reason code platform_not_licensed.

404 Not found

Code	Meaning	What to do
`resource_not_found`	No such object for this account.	Check the ID, the key’s mode, and `Reflections-Account`.

409 Conflict

Code	Meaning	What to do
`idempotency_key_in_use`	The first request with this key is still running. A live check still evaluating is not this error: it returns `202` with `status: "checking"`.	Retry with the same key after a short wait.
`generation_already_submitted`	This check’s candidate already has a generation.	List generations with `check` and use the existing one.
`authorization_consumed`	Every generation the check allowed (`max_generations`) was already submitted.	Run a new check for further outputs.
`check_not_allowed`	The generation names a check whose decision is not `allow`.	Do not submit. Handle the check’s decision.
`check_expired`	The check’s authorization expired before this call.	Run a new check.
`escalation_closed`	The escalation was already resolved, expired or cancelled.	Retrieve the check or generation for its outcome.
`license_draft_closed`	The draft was already signed, declined, discarded or expired.	Retrieve the draft. Create a new one to change terms.
`invalid_state_transition`	The object’s status does not allow this action, such as resuming a license that is not suspended or disputing a paid statement. `detail` names the status.	Retrieve the object and act on its current status.
`session_not_active`	The session ended or was terminated.	Stop output now. Start a new session only if a new check would allow it.

413 Payload too large

Code	Meaning	What to do
`payload_too_large`	Inline media is over 10 MB, or a multipart upload is over 100 MB.	Upload the file and send its ID. For files over 100 MB, use the JSON upload URL, up to 5 GB.

422 Unprocessable

Code	Meaning	What to do
`idempotency_key_reused`	This key was used with a different body or endpoint.	Use a new key for a new request.
`artifact_digest_mismatch`	The bytes do not match the `sha256` you declared.	Recompute the digest over the exact bytes you send.

429 Too many requests

Code	Meaning	What to do
`rate_limited`	You exceeded a rate limit.	Wait `Retry-After` seconds, then retry with the same key. See Rate limits.

5xx Server errors

Status	Code	Meaning	What to do
500	`internal_error`	An unexpected failure on our side.	Retry with the same key, with backoff.
503	`service_unavailable`	Reflections is temporarily unavailable.	Do not generate a named talent. Retry with the same key after `Retry-After`.
504	`evaluation_timeout`	A verification did not finish in time. Only verifications return it; checks escalate instead.	Retry, or verify by receipt instead of by file.

A 503 or a timeout on a check is not permission. Without an allow and an unexpired authorization, do not generate a named talent. See Caching and outages.

Reason codes

Why a use was denied or escalated, and what to show.

Idempotency

Retry safely with the same key.

​The problem format

​Handling errors

​Error codes

​400 Bad request

​401 Unauthorized

​403 Forbidden

​404 Not found

​409 Conflict

​413 Payload too large

​422 Unprocessable

​429 Too many requests

​5xx Server errors

​Related

Reason codes

Idempotency

The problem format

Handling errors

Error codes

400 Bad request

401 Unauthorized

403 Forbidden

404 Not found

409 Conflict

413 Payload too large

422 Unprocessable

429 Too many requests

5xx Server errors

Related