Errors

Two different things get called an error here, and they are worth separating.

Transport errors are HTTP status codes: your request was malformed, your credentials were wrong, or the service is unwell. These are on this page.

Check outcomes are 200 responses whose result says the check did not succeed: member_not_found, invalid_credentials, failed. Those are on the results page. Retrying the HTTP call does not change them.

Status codes

Code	When	Retry?
`400`	Malformed request: no `tpa_name`, an Emirates ID that does not start with `784`, a date filter that is not `YYYY-MM-DD`.	No, fix the request.
`401`	Credentials rejected. Five distinct causes; see Authentication.	No.
`404`	Task not found, or found but owned by a different clinic. Deliberately the same response.	No.
`422`	The request body was not valid JSON, or a query parameter was the wrong type.	No.
`500`	Unexpected server error.	Yes, once, with backoff.
`503`	Only from `bulk/create-tasks` and `get-eligibility-results`, which are not available.	No.

Error bodies

create-task returns its own envelope on a 400:

{
  "success": false,
  "message": "TPA or Insurance name not provided",
  "data": null
}

Sample not captured yet

create-task/error-400-no-tpa will be filled in once the sample capture pass has run against a completed production task.

Sample not captured yet

create-task/error-400-bad-eid will be filled in once the sample capture pass has run against a completed production task.

Everything else returns the framework's standard shape:

{ "detail": "Invalid API key" }

Sample not captured yet

create-task/error-401 will be filled in once the sample capture pass has run against a completed production task.

Two envelopes, one API

create-task 400s use { success, message, data }; every other error uses { detail }. Handle both: reading message on a 401 gets you undefined.

Retry guidance

Never retry a create-task that returned 2xx. You got a task id; the check is running. A second call runs a second real portal session, doubles your rate-limit consumption at the payer, and gives you two task ids for one patient.
Do retry polls. A 5xx on eligibility-result says nothing about the task. Retry the poll, not the create.
Back off on 5xx. Exponential, starting at a few seconds. A tight retry loop against a struggling service makes it worse.
Do not retry 4xx. Nothing about the next identical request will differ.
Do not retry invalid_credentials or backoff outcomes. Repeated attempts cause the payer to lock the clinic's account, and unlocking it requires manual intervention. The backoff outcome exists to prevent that.

Timeouts

Set a generous client-side timeout on create-task. It dispatches to a queue and should return quickly, but a slow response is not a failure you want to retry. A create-task that times out on your side may well have been accepted, and sending it again creates a second real portal session for the same patient. Record the attempt when you send it and reconcile against the task_id you get back, rather than firing a blind retry.

Status codes

Error bodies

Retry guidance

Timeouts

On this page