YaqeenDocs
Back to Yaqeen

Help

Troubleshooting

Find the symptom you see, learn the cause, and apply the fix. Built from real error codes and behaviours.

Each entry gives the symptom, the cause and the fix. Errors use one shape, {code, message}, so search this page for the code you received. The full list of statuses is in Errors. Last reviewed: 2026-11-15.

Sign-in and access#

You get 429 when you sign in#

Symptom. POST /api/v1/auth/login/ answers 429 and a Retry-After header.

Cause. Sign-in is limited per address, per username and address together, and per username across all addresses. Several wrong passwords in a row trigger it.

Fix. Wait for the number of seconds in Retry-After, then try once with the right password. If a person is locked out by mistake, ask your Yaqeen contact to clear the lock.

Google sign-in answers account_pending#

Symptom. POST /api/v1/auth/google/ answers 403 account_pending.

Cause. This is the first Google sign-in for that address. The account exists but is switched off until an admin approves it.

Fix. An admin finds it with GET /api/v1/users/?is_active=false and sends PATCH /api/v1/users/{id}/ with {"is_active": true}. See Approve a sign-up.

Google sign-in answers email_in_use#

Symptom. 409 email_in_use on the Google button.

Cause. A password account already uses that address as its username. We never link by email, because anyone who controls a Google address with the same name could take the account over.

Fix. Sign in with the password, or ask an admin to link the accounts.

A write fails with 403 and the message starts with CSRF Failed#

Symptom. A POST, PUT or DELETE with a session cookie answers 403.

Cause. A session needs a CSRF token on every write.

Fix. Call GET /api/v1/auth/csrf/, then send the csrftoken cookie value in the X-CSRFToken header. Over HTTPS, also send a Referer header. See Authentication.

You get 401 with an API key#

Symptom. That API key is not valid, has expired or was revoked.

Cause. The key is mistyped, expired, revoked or its service account is switched off. A rotated key stops working 24 hours after rotation.

Fix. Check the prefix: yq_live_ for your organization and yq_test_ for the sandbox. Ask an admin to create a new key. The key is shown only once, so copy it when it is created.

You get 403 with This key's scopes do not allow that.#

Cause. A key can do only what its scopes allow: read for GET requests, decide for the decision endpoints, ingest for the two ingest endpoints. No key can reach users, keys, webhooks, privacy, usage or sandboxes.

Fix. Create a key with the scope you need, or do the action with an admin session.

A record exists but you get 404#

Cause. A 404 also means the record belongs to another organization. A merchant sees only its own owner's records, and a yq_test_ key sees only the sandbox. A merchant also cannot see a hold until a reviewer approves it.

Fix. Check that you use the key or account of the organization that owns the record. See Organizations.

Cause. The link was already used, ended after 60 minutes, was replaced by a newer link for the same person, or the account is switched off.

Fix. Ask an admin for a new link with POST /api/v1/users/{id}/reset-link/. If the password is refused with invalid, the message lists why: a password needs at least 12 characters, cannot be a common password, cannot be all digits and cannot be too similar to the username.

An invitation answers invalid_invite or username_taken#

Cause. The invitation link was used, cancelled or ended after 7 days, or the username you chose exists.

Fix. Choose another username, or ask an admin to send a new invitation.

Limits#

You get 429 with an API key#

Symptom. Too many calls for this key. Slow down and retry. or The daily call limit of the plan is used up.

Cause. Each key has a limit per minute (120 by default, from 1 to 6,000). The plan has a daily call limit (50,000 by default). Some endpoints have their own limits: decisions 60 a minute, data loads 30 an hour, password changes 10 an hour.

Fix. Wait for Retry-After. For the per-minute limit, an admin can create a key with a higher rate_per_minute. For the daily limit, contact us to raise the plan. An admin can only lower it. See Rate limits and pagination.

Loading data#

400 not_hashed#

Cause. You sent a raw national ID, phone, email or bank account.

Fix. Hash the value with your key and send the 64-character hash. Yaqeen never accepts the raw value. See Load your data.

400 unknown_store, unknown_owner or a similar unknown_... code#

Cause. A row refers to something not loaded yet. The message gives the position of the row.

Fix. Load parents first: owners, then stores, then the tables that refer to them. A batch is one transaction, so a failed batch loaded nothing. Fix the named row and send the batch again.

payout_has_open_hold, store_changed or owner_changed#

Cause. While a payout has an open hold (recommended or approved), the feed cannot change its amount or timing, and answers 409. A payout cannot move to another store, an order cannot move to another store, and a store cannot move to another owner. These answer 400.

Fix. For an open hold, decide the hold first and then send the update. For the others, send the row with the original store or owner.

413 too_many_rows or too_large#

Cause. A feed batch is limited to 5,000 rows. A zip upload is limited to 300 MB.

Fix. Split the feed into batches of 5,000 rows or fewer. Remove files from the zip that are not data tables.

Holds and appeals#

202 with pending_approval#

Cause. This is not an error. The change needs a second person, for example because the payout is above 5,000 SAR.

Fix. Ask another reviewer or admin to decide it at POST /api/v1/approvals/{id}/decision/. The request expires after 24 hours. See Second-person approval.

403 same_person or Your role cannot approve this change.#

Cause. The person who asked cannot approve their own request. Policy and account changes need an admin.

Fix. Ask a different eligible person.

409 bad_transition#

Cause. The hold is not in a state that allows the decision. A recommended hold can be approved or rejected, and an approved hold can be released. A rejected or released hold is final.

Fix. Read the hold's status first. See Hold statuses.

400 note_required#

Cause. Rejecting, releasing, rejecting an appeal and accepting an appeal all need a short note.

Fix. Add a note that says why.

409 appeal_closed or already_open#

Cause. The appeal window ended (14 days after approval by default), or the hold already has an open appeal. Only an approved hold can be appealed.

Fix. Check appeal_by on the hold. After that date a new appeal cannot be filed.

An appeal document is refused#

Cause. bad_type: only PDF, JPEG and PNG are accepted. bad_size: a file is up to 10 MB. too_many_documents: an appeal holds at most five files. upload_missing: the file did not arrive before you confirmed. storage_off (503): document upload is not switched on.

Fix. Correct the file, upload it to the signed form, then confirm.

A retried decision answers 422 or 409#

Cause. idempotency_key_reused (422): the same Idempotency-Key was sent with a different body. in_progress (409): the first request with that key is still running.

Fix. Use a new key for a new decision. For in_progress, retry in a moment. See Safe retries.

Search and setup#

Search returns nothing#

Cause. The search needs at least 2 characters. It matches a store id exactly or part of a store name, and returns open holds on those stores only. It is for staff roles.

Fix. Search by the store id or a longer part of the name.

The onboarding checklist step does not turn done#

Cause. The four steps read real data. key is done when your organization has an API key, data when it has a payout, hold when it has a hold, and decision when a hold has been approved, rejected or released.

Fix. Do the step named in next. The checklist is for staff roles.

Still stuck#

Send your Yaqeen contact the code and message, the time of the request and your organization name. Do not send keys, tokens or passwords.

Up Down to moveEnter to openEsc to close