How-to guide
Handle errors
Read an API error, decide whether to retry, and fix the cause for each status code.
This guide shows how to handle an error from the API in your code. It is for engineers who call Yaqeen from another system. You need the status code and the body of the response.
Read the error#
Most errors have a JSON body with a code and a message:
{ "code": "note_required", "message": "Say why in a short note." }Use the code in your program. It is stable. Show the message to a person. It can change.
A bad field gets 400, the code error and a fields object:
{ "code": "error", "message": "The request could not be processed.", "fields": { "decision": ["This field is required."] } }Do not rely on the body of a 5xx answer. Use the status code.
Decide what to do#
| Status | Do this | Retry the same request? |
|---|---|---|
202 | The change waits for a second person. Keep the approval_id and check it later. | No |
400 | Fix the request using code, message and fields. | No, not until you change it |
401 | Sign in again, or replace the key. | No, not until you fix the sign-in |
403 | Use an account or key with the right role or scope. | No |
404 | Check the id. The item may belong to another organization. | No |
409 | The state changed. Read the item again and decide. | Only in_progress |
413 | Send a smaller batch or file. | No, not until you shrink it |
422 | You reused an idempotency key with a different body. Use a new key. | No |
429 | Wait for the seconds in Retry-After. | Yes, after the wait |
5xx | Yaqeen had a problem. Wait and send the request again. | Yes, with a longer wait each time |
A 4xx answer means the request itself must change, so sending it again gives the same answer. The exceptions are 429 and 409 in_progress.
Retry without doing the work twice#
Before you retry a hold decision, send an Idempotency-Key header with the first attempt. A retry with the same key and body returns the first answer and decides nothing twice. Yaqeen does not keep the answer to a 5xx, so retrying after a 5xx runs the request. See Safe retries.
Other endpoints ignore that header. Before you retry them, read the item to see if the first request worked.
Handle a waiting change#
A 202 answer has this body:
{ "status": "pending_approval", "message": "This change needs a second person. It is waiting for approval.", "approval_id": "3f9a0c52-6b1e-4d7a-8c20-1e5b7a9d4f33", "reasons": ["The amount 7,500.00 SAR is above the limit of 5,000.00 SAR."] }The change has not run. Read it with GET /api/v1/approvals/{approval_id}/. A waiting request ends after the expiry time in the approval settings (24 hours by default). See Second-person approval.
Handle a bulk decision#
A bulk decision answers 200 even when some holds fail. Check each item in results. A failed item has its own code and message. Fix and resend only the failed holds, with a new idempotency key.
Handle a data load#
A load is one transaction. If one row is wrong, no row loads. The message names the row, such as row 3: amount is not a number. Fix the row and send the batch again. To find problems before you load, use POST /api/v1/ingest/connect/ with its default dry run. See Load your data.
Handle a 429#
- Read the
Retry-Afterheader. It gives the seconds to wait. - Stop sending calls with that key or account until the time passes.
- Send the call again.
If you hit the limit often, slow your calls or ask an admin to raise the key's rate_per_minute or the plan's daily limit. See Rate limits and pagination.
Ask for help#
When an error is not in Errors, or a 5xx continues, send these to your Yaqeen contact:
- the status code and the body
- the time of the call, with the time zone
- the method and the path, without ids of real people
- your organization name
If it does not work#
- You get
403with a key that should work: check the key's scopes and the role they map to. See Authentication. - You get
404for an item you can see elsewhere: you may be signed in to a different organization, or you are using a sandbox key.
Next steps#
- Errors: every code with its fix.
- Safe retries: the idempotency header.
- Rate limits and pagination: the limits behind
429. - Troubleshooting: fixes for common symptoms.