How to handle API errors
Every DiligenceID error has the same shape:
{
"error": {
"code": "IssuerNotReady",
"message": "The issuer cannot be activated.",
"target": "issuer",
"details": [],
"innerError": {
"date": "2026-08-30T04:11:02Z",
"requestId": "req_5f2c9a1e4b7d4c6f8a2e",
"clientRequestId": "checkout-8891"
}
}
}
Branch on code, never on message
code is the stable machine-readable contract. message is written for a human reading a log and may be
reworded at any time. Parsing it will break.
Handle these statuses
| Status | Meaning | Do |
|---|---|---|
400 |
Invalid request | Fix the request. Do not retry unchanged |
401 |
Authentication failed | Check the key. Do not retry |
403 |
Missing scope | Check the key's scopes. Do not retry |
404 |
Not visible to you | Do not retry. It may exist for someone else |
409 |
Conflict, or idempotency key reused with a different payload | Investigate. Do not blind-retry |
412 |
Stale If-Match |
Re-read, re-apply, retry |
429 |
Throttled | Back off and retry |
5xx |
Unexpected failure | Retry with backoff |
Retrying a 4xx unchanged will fail identically. The only routinely retryable statuses are 429, 5xx and
412 after re-reading.
Always log the request id
x-ms-request-id: req_5f2c9a1e4b7d4c6f8a2e
It is also in error.innerError.requestId. A support request without it is largely unanswerable; with it, the
exact request can be found.
Retrying a mutating call needs an idempotency key
A retry without one may issue a second credential. See use idempotency.
What errors never contain
No exception types, stack traces, database errors, connection strings, Azure resource identifiers, key vault names, tokens, credential proofs, cookies, key material, or anything about resources in another tenant. If you are looking for a stack trace to diagnose something, quote the request id instead.