YaqeenDocs
Back to Yaqeen

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:

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

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

StatusDo thisRetry the same request?
202The change waits for a second person. Keep the approval_id and check it later.No
400Fix the request using code, message and fields.No, not until you change it
401Sign in again, or replace the key.No, not until you fix the sign-in
403Use an account or key with the right role or scope.No
404Check the id. The item may belong to another organization.No
409The state changed. Read the item again and decide.Only in_progress
413Send a smaller batch or file.No, not until you shrink it
422You reused an idempotency key with a different body. Use a new key.No
429Wait for the seconds in Retry-After.Yes, after the wait
5xxYaqeen 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:

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

  1. Read the Retry-After header. It gives the seconds to wait.
  2. Stop sending calls with that key or account until the time passes.
  3. 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 403 with a key that should work: check the key's scopes and the role they map to. See Authentication.
  • You get 404 for an item you can see elsewhere: you may be signed in to a different organization, or you are using a sandbox key.

Next steps#

Up Down to moveEnter to openEsc to close