YaqeenDocs
Back to Yaqeen

Reference

Errors

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.

json
{ "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:

json
{ "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#

StatusMeaning
200, 201, 204The request worked.
202Accepted but waiting for a second person. The body has status: pending_approval and an approval_id.
400The request is wrong. The code says how.
401No sign-in, or a bad or expired API key, or a wrong password at sign-in.
403Your role or your key's scopes do not allow it.
404The item does not exist, or it belongs to another organization.
409The request conflicts with the current state.
413A batch or a file is too large.
422An idempotency key was reused with a different body.
429Too many calls. Wait for Retry-After seconds.
503A feature that is not switched on.

General#

CodeStatusFix
error400Read fields. Correct the named values and send the request again.
error401Sign in again, or send a valid API key.
error403Use an account or key with the role or scope the endpoint needs. See Roles and permissions.
error404Check the id. The item may belong to another organization.
error405Use the method that the endpoint allows.
error429Wait for the seconds in Retry-After, then send the request again.
forbidden403Your role cannot make this change. The message names the role that can.
invalid400A value failed a check. The message lists each problem, such as a password that is too short.
bad_credentials401Check the username and password. Sign-in is limited, so wait if you see 429.
google_failed401Google did not accept the token or has not confirmed the email. Try the Google button again, or use a password.
account_pending403A new Google account waits for an admin to switch it on. Ask an admin.
account_off403The account is switched off. Ask an admin.
email_in_use409The email already has a password account. Ask an admin to link it.
google_off404Google sign-in is not set up on this server.
invalid_username400A username needs at least 3 characters, only letters, numbers and . + - _, and no @.
bad_email400Send a valid email address.
signups_paused503Too many accounts are waiting for approval, so new sign-ups are paused. Ask an admin.
google_unavailable503Yaqeen 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_again409Two first Google sign-ins arrived together. Send it again.

Idempotency#

CodeStatusFix
bad_idempotency_key400Use 8 to 128 letters, digits, - or _.
idempotency_key_reused422Send the original body with this key, or use a new key.
in_progress409The first request with this key is still running. Wait and send it again.

Holds and appeals#

CodeStatusFix
no_reason400Give a hold at least one reason.
bad_reason400Give each reason a code and text in Arabic and English.
already_open409The payout already has an open hold, or the hold already has an open appeal. Decide the open one first.
bad_decision400Send approve, reject or release for a hold, and accept or reject for an appeal.
bad_transition409The status does not allow this change. Read the hold and check Hold statuses.
note_required400Add a short note that says why.
bad_amount400Send an amount above 0 and no more than the payout.
statement_required400Add the statement for the appeal.
appeal_closed409The appeal window has ended. The message gives the last day.
bad_status400Use a status from the list in Hold statuses, or open or closed for a case.
bad_filter400Correct the filter value. The message says what it expects.
reason_has_no_orders400Use a reason code that can be listed as orders. The message names them.
bad_policy400Send the whole policy as a JSON object that passes the checks in the message.

Appeal documents#

CodeStatusFix
appeal_not_open409The appeal is already decided. Files can be added only while it is open.
bad_type400Send a PDF, a JPEG or a PNG file.
bad_size400Send a file of 1 byte to 10 MB.
bad_name400Give the file a name.
too_many_documents409An appeal can have 5 files. Send the most useful ones.
upload_missing409The file has not arrived. Upload it, then confirm again.
upload_mismatch400The file differs from what was declared. Start the upload again.
storage_off503Document upload is not switched on. The operator must set the bucket.
token_in_use409The phone token belongs to another account. Remove the device there first.

Cases and reviews#

CodeStatusFix
text_required400A note or a message cannot be empty. Add text.
bad_assignee400Choose an active reviewer or admin.
bad_outcome400Choose one of the outcomes in the message.
holds_undecided409Decide every hold in the case first.
bad_result400Send agree or disagree.
same_person403A different person has to do this. Ask another reviewer.
already_checked409Another reviewer has already checked this conclusion.
bad_month400Send the month as 2026-11.
bad_format400Send as=json or as=html.
bad_range400Send from and to as dates, at most 92 days apart.

Review queue#

CodeStatusFix
too_many_claims409Finish or release one of the items you hold.
queue_empty404Nothing is waiting. Check again later.
busy409Someone else took the item first. Ask for the next one.
bad_limit400Send a number inside the range in the message.
bad_days400Send days as a whole number from 1 to 365.

Second-person approvals#

CodeStatusFix
unknown_kind400The kind of change is not one Yaqeen knows. Use the endpoint for that change.
own_account409You cannot change your own role or switch yourself off. Ask another admin.
same_person403A second person has to approve, not the person who asked.
bad_decision400Send approve or reject.
not_pending409The request is already decided, cancelled or expired. Read it to see its status.
bad_limit400A limit must be above 0, and the expiry must be 1 to 168 hours.

API keys and plan#

CodeStatusFix
name_required400Give the key a name.
bad_scopes400Choose from read, decide, ingest, scim, mcp.
bad_days400A key lasts 1 to 365 days.
bad_rate400Choose 1 to 6000 calls a minute.
no_sandbox409Create the sandbox first.
bad_limit400A plan limit cannot be negative.
bad_price400A price must be a number that is not negative.

Sandbox#

CodeStatusFix
nested409A sandbox cannot have a sandbox. Use the main organization.
exists409The sandbox already exists. Use it.
no_sandbox409Create the sandbox first.
not_empty409The sandbox already has data. Reset it, then load it again.

Data loading#

CodeStatusFix
unknown_table400Use a table the feed accepts. The message lists them.
incomplete_mapping400Map the fields named in the message.
name_required400Give the mapping a name.
unknown_mapping404Save the mapping first, or use its exact name.
bad_rows400Send 1 to 5,000 rows, as a list.
bad_row400Fix the row named in the message. It is missing a field, is not an object, or has a bad amount or time.
too_many_rows413Send 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_customer400Load the item the row points to first. The message gives the row and the id.
owner_changed400A store cannot move to another owner. Load a new store.
store_changed400An order or a payout cannot move to another store.
payout_has_open_hold409The payout is under review. Its amount and timing cannot change until the hold is closed.
replace_needs_one_org409Load without replace, or use an organization that is alone.
too_large413The upload must be 300 MB or smaller.
bad_zip400Send a zip file.
unexpected_file400Remove the file that is not a data table.
missing_table400Add the tables named in the message to the zip.
not_hashed400Send the 64-character hash, not the raw value.

Webhooks#

CodeStatusFix
bad_url400Use an https:// address of a public host that exists.
bad_events400Choose from the events in Webhook events.
too_many409Remove an endpoint. An organization can have 5 active ones.

People and sign-in#

CodeStatusFix
invalid_role400Choose reviewer or admin. A merchant stays a merchant.
role_required400Activating a self-signed-up account that has never signed in needs a role in the same PATCH /api/v1/users/{id}/.
owner_required400Link a merchant account to one owner.
unknown_owner400Use an owner id that exists.
last_admin409Make another admin first. The last active admin cannot be removed.
bad_password400The current password is wrong, or the new one fails the checks in the message.
username_taken409Choose another username.
bad_email400Send a valid email address.
already_invited409That address already has an open invitation. Revoke it or wait.
invalid_invite400The invitation is not valid. Ask an admin for a new one.
closed409The invitation or application is already closed.
invalid_link400The reset link is used, ended or not valid. Ask an admin for a new one.
bad_value400In SCIM, send active as true or false.

New-store applications#

CodeStatusFix
bad_type400Use a business type from the list in the message.
closed409The application is already decided. Submit a new one.
unknown_document400Use a paper from this application's checklist.
bad_decision400Send approve, reject or needs_info.
note_required400Say why, so the applicant can be told.
papers_missing409Mark the missing papers as received first. The message names them.

Reserves and disputes#

CodeStatusFix
bad_amount400Send an amount above 0. A dispute cannot be more than its payout.
bad_kind400Use fixed or rolling for a reserve, and chargeback or dispute for a dispute.
reason_required400Say why the money is held back.
bad_days400Hold for 1 to 365 days. Every reserve ends.
unknown_store400Use a store id that exists.
bad_request400Choose a result (released or applied, won or lost) and give a reason.
already_closed409The reserve is already closed.
dispute_reserve409Decide the dispute to close its reserve.
unknown_payout404Use a payout id that exists.
statement_required400Write the answer.
not_open409The dispute no longer takes an answer.
too_late409The response date has passed.
already_decided409The dispute is already decided.

Suppressions and rules#

CodeStatusFix
bad_scope400Use store, owner or bank_account.
reason_required400Say why this should not be flagged.
bad_days400Choose 1 to 180 days. Every entry ends.
unknown_target400Use a store, owner or bank account that exists.
note_required400Say why the suppression should end.
already_ended409The suppression has already ended.
bad_key400A rule key is 3 to 40 lowercase letters, digits or _.
bad_action400A rule action is flag or skip.
bad_conditions400Use 1 to 5 conditions with a known field, a known operator and a number.
bad_score400A rule score is above 0 and at most 1.

Policy proposals#

CodeStatusFix
name_required400Give the proposal a name.
bad_days400Shadow time is 0 to 60 days.
backtest_first409Run the backtest before the shadow run.
bad_state409The proposal's status does not allow this step. Read it.
gates_not_met409The checks in the message have not passed. Run them again.
nothing_to_restore409There is no earlier policy version to go back to.

Privacy#

CodeStatusFix
unknown_owner404Use an owner id that exists.
bad_kind400Use access or erasure.
reason_required400Say why.
already_closed409The request is already closed.
blocked409A reason in the message blocks the request. Add a note to refuse it.

Messages, assistant and saved views#

CodeStatusFix
text_required400A message cannot be empty.
empty400Write a message first.
too_long400Keep an assistant message under 2,000 characters.
bad_days400An assistant action takes 1 to 60 days.
not_found404The chat or the reply was not found, or it belongs to someone else.
already_rated409You already rated this reply.
too_many_views409Delete 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" }.

WhereCodeStatusFix
MCPerror401The token is not valid, has expired or was revoked, or the key is wrong. Sign in again or send a valid key.
MCPforbidden403The key lacks the mcp scope, the browser Origin is not listed in MCP_ALLOWED_ORIGINS, or an admin switched MCP off for the organization.
MCPtoo_large413The message is over 64 KB. Send less.
MCPerror405Use POST. GET and DELETE are not allowed.
MCPerror429Over 120 calls a minute, or over the plan's daily limit. Wait for Retry-After.
MCP, JSON-RPC-32700400The body is not valid JSON.
MCP, JSON-RPC-32600400Send one JSON-RPC 2.0 message, not a batch, and do not send responses.
MCP, JSON-RPC-32601404The method does not exist.
MCP, JSON-RPC-32602200The tool is unknown or not offered to your role, or its arguments are wrong.
MCP, JSON-RPC-32022400The protocol version is not served. The reply lists the supported ones.
OAuthinvalid_client401The client is unknown, or its metadata document could not be read or does not match its address.
OAuthinvalid_client_metadata400The registration needs 1 to 10 safe redirect addresses and no client secret.
OAuthinvalid_grant400The code or refresh token is wrong, used, expired or does not match the request. Sign in again.
OAuthinvalid_request400PKCE with S256 is required.
OAuthinvalid_target400The resource must be the MCP address of this server.
OAuthunsupported_grant_type400Use authorization_code or refresh_token.
OAuthslow_down429Too many token or registration requests. Wait a minute.
OAuthaccess_deniedredirectStaff accounts only, or MCP is switched off for the organization, or the person pressed Deny.

Up Down to moveEnter to openEsc to close