Every error code the API returns, with its HTTP status and a one-line fix, grouped by area.
This page lists the error codes the API returns, grouped by area. For what to do about each status class, read Handle errors.
The error shape#
An error has a stable code for programs and a plain message for people.
{ "code": "papers_missing", "message": "Still missing: bank_letter." }
Errors that come from the web framework have the code error. A bad field gets 400 and a fields object that names each field and its problem:
{ "code": "error", "message": "The request could not be processed.", "fields": { "decision": ["This field is required."] } }
An error with no fields key has the two keys code and message only. A throttle error also has the Retry-After header.
Status codes#
| Status | Meaning |
|---|
| 200, 201, 204 | The request worked. |
| 202 | Accepted but waiting for a second person. The body has status: pending_approval and an approval_id. |
| 400 | The request is wrong. The code says how. |
| 401 | No sign-in, or a bad or expired API key, or a wrong password at sign-in. |
| 403 | Your role or your key's scopes do not allow it. |
| 404 | The item does not exist, or it belongs to another organization. |
| 409 | The request conflicts with the current state. |
| 413 | A batch or a file is too large. |
| 422 | An idempotency key was reused with a different body. |
| 429 | Too many calls. Wait for Retry-After seconds. |
| 503 | A feature that is not switched on. |
General#
| Code | Status | Fix |
|---|
error | 400 | Read fields. Correct the named values and send the request again. |
error | 401 | Sign in again, or send a valid API key. |
error | 403 | Use an account or key with the role or scope the endpoint needs. See Roles and permissions. |
error | 404 | Check the id. The item may belong to another organization. |
error | 405 | Use the method that the endpoint allows. |
error | 429 | Wait for the seconds in Retry-After, then send the request again. |
forbidden | 403 | Your role cannot make this change. The message names the role that can. |
invalid | 400 | A value failed a check. The message lists each problem, such as a password that is too short. |
bad_credentials | 401 | Check the username and password. Sign-in is limited, so wait if you see 429. |
google_failed | 401 | Google did not accept the token or has not confirmed the email. Try the Google button again, or use a password. |
account_pending | 403 | A new Google account waits for an admin to switch it on. Ask an admin. |
account_off | 403 | The account is switched off. Ask an admin. |
email_in_use | 409 | The email already has a password account. Ask an admin to link it. |
google_off | 404 | Google sign-in is not set up on this server. |
invalid_username | 400 | A username needs at least 3 characters, only letters, numbers and . + - _, and no @. |
bad_email | 400 | Send a valid email address. |
signups_paused | 503 | Too many accounts are waiting for approval, so new sign-ups are paused. Ask an admin. |
google_unavailable | 503 | Yaqeen could not reach Google to check the token. Nobody signs in this way until it can. Try again in a moment, or use a password. |
try_again | 409 | Two first Google sign-ins arrived together. Send it again. |
Idempotency#
| Code | Status | Fix |
|---|
bad_idempotency_key | 400 | Use 8 to 128 letters, digits, - or _. |
idempotency_key_reused | 422 | Send the original body with this key, or use a new key. |
in_progress | 409 | The first request with this key is still running. Wait and send it again. |
Holds and appeals#
| Code | Status | Fix |
|---|
no_reason | 400 | Give a hold at least one reason. |
bad_reason | 400 | Give each reason a code and text in Arabic and English. |
already_open | 409 | The payout already has an open hold, or the hold already has an open appeal. Decide the open one first. |
bad_decision | 400 | Send approve, reject or release for a hold, and accept or reject for an appeal. |
bad_transition | 409 | The status does not allow this change. Read the hold and check Hold statuses. |
note_required | 400 | Add a short note that says why. |
bad_amount | 400 | Send an amount above 0 and no more than the payout. |
statement_required | 400 | Add the statement for the appeal. |
appeal_closed | 409 | The appeal window has ended. The message gives the last day. |
bad_status | 400 | Use a status from the list in Hold statuses, or open or closed for a case. |
bad_filter | 400 | Correct the filter value. The message says what it expects. |
reason_has_no_orders | 400 | Use a reason code that can be listed as orders. The message names them. |
bad_policy | 400 | Send the whole policy as a JSON object that passes the checks in the message. |
Appeal documents#
| Code | Status | Fix |
|---|
appeal_not_open | 409 | The appeal is already decided. Files can be added only while it is open. |
bad_type | 400 | Send a PDF, a JPEG or a PNG file. |
bad_size | 400 | Send a file of 1 byte to 10 MB. |
bad_name | 400 | Give the file a name. |
too_many_documents | 409 | An appeal can have 5 files. Send the most useful ones. |
upload_missing | 409 | The file has not arrived. Upload it, then confirm again. |
upload_mismatch | 400 | The file differs from what was declared. Start the upload again. |
storage_off | 503 | Document upload is not switched on. The operator must set the bucket. |
token_in_use | 409 | The phone token belongs to another account. Remove the device there first. |
Cases and reviews#
| Code | Status | Fix |
|---|
text_required | 400 | A note or a message cannot be empty. Add text. |
bad_assignee | 400 | Choose an active reviewer or admin. |
bad_outcome | 400 | Choose one of the outcomes in the message. |
holds_undecided | 409 | Decide every hold in the case first. |
bad_result | 400 | Send agree or disagree. |
same_person | 403 | A different person has to do this. Ask another reviewer. |
already_checked | 409 | Another reviewer has already checked this conclusion. |
bad_month | 400 | Send the month as 2026-11. |
bad_format | 400 | Send as=json or as=html. |
bad_range | 400 | Send from and to as dates, at most 92 days apart. |
Review queue#
| Code | Status | Fix |
|---|
too_many_claims | 409 | Finish or release one of the items you hold. |
queue_empty | 404 | Nothing is waiting. Check again later. |
busy | 409 | Someone else took the item first. Ask for the next one. |
bad_limit | 400 | Send a number inside the range in the message. |
bad_days | 400 | Send days as a whole number from 1 to 365. |
Second-person approvals#
| Code | Status | Fix |
|---|
unknown_kind | 400 | The kind of change is not one Yaqeen knows. Use the endpoint for that change. |
own_account | 409 | You cannot change your own role or switch yourself off. Ask another admin. |
same_person | 403 | A second person has to approve, not the person who asked. |
bad_decision | 400 | Send approve or reject. |
not_pending | 409 | The request is already decided, cancelled or expired. Read it to see its status. |
bad_limit | 400 | A limit must be above 0, and the expiry must be 1 to 168 hours. |
API keys and plan#
| Code | Status | Fix |
|---|
name_required | 400 | Give the key a name. |
bad_scopes | 400 | Choose from read, decide, ingest, scim, mcp. |
bad_days | 400 | A key lasts 1 to 365 days. |
bad_rate | 400 | Choose 1 to 6000 calls a minute. |
no_sandbox | 409 | Create the sandbox first. |
bad_limit | 400 | A plan limit cannot be negative. |
bad_price | 400 | A price must be a number that is not negative. |
Sandbox#
| Code | Status | Fix |
|---|
nested | 409 | A sandbox cannot have a sandbox. Use the main organization. |
exists | 409 | The sandbox already exists. Use it. |
no_sandbox | 409 | Create the sandbox first. |
not_empty | 409 | The sandbox already has data. Reset it, then load it again. |
Data loading#
| Code | Status | Fix |
|---|
unknown_table | 400 | Use a table the feed accepts. The message lists them. |
incomplete_mapping | 400 | Map the fields named in the message. |
name_required | 400 | Give the mapping a name. |
unknown_mapping | 404 | Save the mapping first, or use its exact name. |
bad_rows | 400 | Send 1 to 5,000 rows, as a list. |
bad_row | 400 | Fix the row named in the message. It is missing a field, is not an object, or has a bad amount or time. |
too_many_rows | 413 | Send at most 5,000 rows a batch. The request check normally answers first with 400 and rows in fields. |
unknown_order, unknown_payout, unknown_owner, unknown_store, unknown_customer | 400 | Load the item the row points to first. The message gives the row and the id. |
owner_changed | 400 | A store cannot move to another owner. Load a new store. |
store_changed | 400 | An order or a payout cannot move to another store. |
payout_has_open_hold | 409 | The payout is under review. Its amount and timing cannot change until the hold is closed. |
replace_needs_one_org | 409 | Load without replace, or use an organization that is alone. |
too_large | 413 | The upload must be 300 MB or smaller. |
bad_zip | 400 | Send a zip file. |
unexpected_file | 400 | Remove the file that is not a data table. |
missing_table | 400 | Add the tables named in the message to the zip. |
not_hashed | 400 | Send the 64-character hash, not the raw value. |
Webhooks#
| Code | Status | Fix |
|---|
bad_url | 400 | Use an https:// address of a public host that exists. |
bad_events | 400 | Choose from the events in Webhook events. |
too_many | 409 | Remove an endpoint. An organization can have 5 active ones. |
People and sign-in#
| Code | Status | Fix |
|---|
invalid_role | 400 | Choose reviewer or admin. A merchant stays a merchant. |
role_required | 400 | Activating a self-signed-up account that has never signed in needs a role in the same PATCH /api/v1/users/{id}/. |
owner_required | 400 | Link a merchant account to one owner. |
unknown_owner | 400 | Use an owner id that exists. |
last_admin | 409 | Make another admin first. The last active admin cannot be removed. |
bad_password | 400 | The current password is wrong, or the new one fails the checks in the message. |
username_taken | 409 | Choose another username. |
bad_email | 400 | Send a valid email address. |
already_invited | 409 | That address already has an open invitation. Revoke it or wait. |
invalid_invite | 400 | The invitation is not valid. Ask an admin for a new one. |
closed | 409 | The invitation or application is already closed. |
invalid_link | 400 | The reset link is used, ended or not valid. Ask an admin for a new one. |
bad_value | 400 | In SCIM, send active as true or false. |
New-store applications#
| Code | Status | Fix |
|---|
bad_type | 400 | Use a business type from the list in the message. |
closed | 409 | The application is already decided. Submit a new one. |
unknown_document | 400 | Use a paper from this application's checklist. |
bad_decision | 400 | Send approve, reject or needs_info. |
note_required | 400 | Say why, so the applicant can be told. |
papers_missing | 409 | Mark the missing papers as received first. The message names them. |
Reserves and disputes#
| Code | Status | Fix |
|---|
bad_amount | 400 | Send an amount above 0. A dispute cannot be more than its payout. |
bad_kind | 400 | Use fixed or rolling for a reserve, and chargeback or dispute for a dispute. |
reason_required | 400 | Say why the money is held back. |
bad_days | 400 | Hold for 1 to 365 days. Every reserve ends. |
unknown_store | 400 | Use a store id that exists. |
bad_request | 400 | Choose a result (released or applied, won or lost) and give a reason. |
already_closed | 409 | The reserve is already closed. |
dispute_reserve | 409 | Decide the dispute to close its reserve. |
unknown_payout | 404 | Use a payout id that exists. |
statement_required | 400 | Write the answer. |
not_open | 409 | The dispute no longer takes an answer. |
too_late | 409 | The response date has passed. |
already_decided | 409 | The dispute is already decided. |
Suppressions and rules#
| Code | Status | Fix |
|---|
bad_scope | 400 | Use store, owner or bank_account. |
reason_required | 400 | Say why this should not be flagged. |
bad_days | 400 | Choose 1 to 180 days. Every entry ends. |
unknown_target | 400 | Use a store, owner or bank account that exists. |
note_required | 400 | Say why the suppression should end. |
already_ended | 409 | The suppression has already ended. |
bad_key | 400 | A rule key is 3 to 40 lowercase letters, digits or _. |
bad_action | 400 | A rule action is flag or skip. |
bad_conditions | 400 | Use 1 to 5 conditions with a known field, a known operator and a number. |
bad_score | 400 | A rule score is above 0 and at most 1. |
Policy proposals#
| Code | Status | Fix |
|---|
name_required | 400 | Give the proposal a name. |
bad_days | 400 | Shadow time is 0 to 60 days. |
backtest_first | 409 | Run the backtest before the shadow run. |
bad_state | 409 | The proposal's status does not allow this step. Read it. |
gates_not_met | 409 | The checks in the message have not passed. Run them again. |
nothing_to_restore | 409 | There is no earlier policy version to go back to. |
Privacy#
| Code | Status | Fix |
|---|
unknown_owner | 404 | Use an owner id that exists. |
bad_kind | 400 | Use access or erasure. |
reason_required | 400 | Say why. |
already_closed | 409 | The request is already closed. |
blocked | 409 | A reason in the message blocks the request. Add a note to refuse it. |
Messages, assistant and saved views#
| Code | Status | Fix |
|---|
text_required | 400 | A message cannot be empty. |
empty | 400 | Write a message first. |
too_long | 400 | Keep an assistant message under 2,000 characters. |
bad_days | 400 | An assistant action takes 1 to 60 days. |
not_found | 404 | The chat or the reply was not found, or it belongs to someone else. |
already_rated | 409 | You already rated this reply. |
too_many_views | 409 | Delete a saved view. You can keep 30. |
MCP and OAuth#
The MCP address answers with the usual { "code", "message" } errors for sign-in and limits, and with JSON-RPC errors for a bad message. The OAuth endpoints under /api/v1/oauth/ follow the OAuth standard instead: the body is { "error", "error_description" }.
| Where | Code | Status | Fix |
|---|
| MCP | error | 401 | The token is not valid, has expired or was revoked, or the key is wrong. Sign in again or send a valid key. |
| MCP | forbidden | 403 | The key lacks the mcp scope, the browser Origin is not listed in MCP_ALLOWED_ORIGINS, or an admin switched MCP off for the organization. |
| MCP | too_large | 413 | The message is over 64 KB. Send less. |
| MCP | error | 405 | Use POST. GET and DELETE are not allowed. |
| MCP | error | 429 | Over 120 calls a minute, or over the plan's daily limit. Wait for Retry-After. |
| MCP, JSON-RPC | -32700 | 400 | The body is not valid JSON. |
| MCP, JSON-RPC | -32600 | 400 | Send one JSON-RPC 2.0 message, not a batch, and do not send responses. |
| MCP, JSON-RPC | -32601 | 404 | The method does not exist. |
| MCP, JSON-RPC | -32602 | 200 | The tool is unknown or not offered to your role, or its arguments are wrong. |
| MCP, JSON-RPC | -32022 | 400 | The protocol version is not served. The reply lists the supported ones. |
| OAuth | invalid_client | 401 | The client is unknown, or its metadata document could not be read or does not match its address. |
| OAuth | invalid_client_metadata | 400 | The registration needs 1 to 10 safe redirect addresses and no client secret. |
| OAuth | invalid_grant | 400 | The code or refresh token is wrong, used, expired or does not match the request. Sign in again. |
| OAuth | invalid_request | 400 | PKCE with S256 is required. |
| OAuth | invalid_target | 400 | The resource must be the MCP address of this server. |
| OAuth | unsupported_grant_type | 400 | Use authorization_code or refresh_token. |
| OAuth | slow_down | 429 | Too many token or registration requests. Wait a minute. |
| OAuth | access_denied | redirect | Staff accounts only, or MCP is switched off for the organization, or the person pressed Deny. |