Getting StartedError Handling
Error Handling
Step-by-step guidance for secure Xaqiiji API integration.
Standard error format
application/json
{ "status": "failed", "code": "BAD_REQUEST", "message": "Validation failed", "errors": [ { "field": "nationalId", "message": "National ID must be exactly 11 digits" } ]}Error table
| HTTP status | Error code | Description |
|---|---|---|
| 400 | BAD_REQUEST | Malformed request or validation failure. |
| 401 | UNAUTHORIZED | Missing, invalid, revoked, or expired API key. |
| 403 | FORBIDDEN | Business inactive or not on an enterprise plan. |
| 404 | NOT_FOUND | Resource not found. |
| 409 | CONFLICT | Idempotency-Key reused with a different payload. |
| 429 | RATE_LIMITED | Too many requests — retry with backoff. |
| 500 | INTERNAL_ERROR | Unexpected server error. |
Retry strategy
Retry 429 and 5xx with exponential backoff. Do not retry 400, 401, 403, or 409 without fixing the request. Always use Idempotency-Key when retrying POST /verify/citizen.
Edit this page
Was this page helpful?