Core concepts

Errors

Errors use HTTP status codes and a stable, snake_case error.code. Branch on the code. error.details is optional and code-specific.

422 Unprocessable Entity

{
  "status": "fail",
  "data": null,
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": {
      "fields": {
        "rules.3.price": ["price must be a decimal string with at most 2 decimals"],
        "reason": ["reason must be at least 3 characters"]
      }
    }
  },
  "metadata": { "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77", "…": "…" }
}

Generic codes#

Any endpoint can return these. Business codes (package_incomplete, claim_not_payable, …) are listed on each endpoint in the reference.

Status	Code	Meaning	Do
400	`bad_request`	Malformed JSON, missing or unknown field, or an action not allowed in the resource's current status.	Fix the request. Don't retry as is.
400	`invalid_scope`	Token request for a scope the client doesn't hold.	Request only granted scopes.
401	`invalid_client`	Wrong client credentials, or client revoked.	Check credentials; ask your account manager.
401	`unauthorized`	Token missing, invalid or expired.	Get a new token and retry once.
403	`missing_permission`	The token lacks the endpoint's scope.	Ask for the scope on the client.
403	`forbidden`	The client can never do this.	Don't retry.
403	`ip_not_allowed`	IP not on the client's allow-list.	Fix the allow-list or call from an allowed IP.
403	`tenant_not_active`	Your company is suspended on Wathiqaty.	Contact your account manager.
404	`not_found`	Doesn't exist, or isn't your company's. `details.resource` names it.	Treat as missing.
408	`request_timeout`	The request took too long.	Retry with the same `Idempotency-Key`.
409	`conflict`	Conflicts with current state, e.g. a duplicate reference.	Reload, then decide.
409	`idempotency_request_is_still_processing`	Same key still running.	Wait 1 s, retry with the same key.
412	`version_conflict`	Changed since you read it.	Reload, re-apply, resend with the new `If-Match`.
413	`payload_too_large`	Body over 100 KB.	Send less.
422	`validation_error`	Field values invalid. `details.fields` maps each path to messages.	Fix the values.
422	`idempotency_key_already_used`	Same key with a different request.	New key for a new action.
429	`rate_limited`	Too many requests.	Wait `Retry-After` seconds.
500	`internal_server_error`	Unexpected error on our side.	Retry with backoff; report the request id if it persists.
503	`service_unavailable`	A dependency is down or we are deploying.	Retry with backoff, honour `Retry-After`.

Retrying#

Retry: network errors, 408, 429, 5xx, and 409 idempotency_request_is_still_processing — always with the same Idempotency-Key.
Refresh and retry once: 401 unauthorized.
Never retry unchanged: any other 4xx.
Back off exponentially with jitter (1 s, 2 s, 4 s … up to 60 s), and honour Retry-After when present.

Pseudocode

async function call(request, attempt = 0) {
  const res = await send(request) // same Idempotency-Key on every attempt
  if (res.ok) return res
  const retryable = [408, 429, 500, 502, 503, 504].includes(res.status)
    || (res.status === 409 && res.code === "idempotency_request_is_still_processing")
  if (res.status === 401 && attempt === 0) {
    await refreshToken()
    return call(request, attempt + 1)
  }
  if (!retryable || attempt >= 6) throw res
  const wait = res.retryAfter ?? Math.min(60, 2 ** attempt) * (0.5 + Math.random())
  await sleep(wait * 1000)
  return call(request, attempt + 1)
}

Status not allowed

Moving a resource to a status its current status doesn't allow (e.g. approving a claim that's still submitted) is 400 bad_request with details.from and details.to. Reload the resource: someone (your staff, the customer, or the system) moved it first.