Fundamentals
Error handling and retries
The Axiym API platform returns structured JSON errors for API-level failures. Use the HTTP status for the primary handling path and the body for validation or domain detail.
Error shape
{
"code": 422,
"message": "Invalid Parameters",
"errors": {
"resource.field": [
{
"code": "invalid_format",
"message": null,
"params": { "value": "123" }
}
]
}
}| Field | Meaning |
|---|---|
code | HTTP status code as a number. |
message | Human-readable summary. Do not treat it as a stable machine code. |
errors | Field-level validation detail, or null when none is available. |
Status handling
| Status | Meaning | Retry? |
|---|---|---|
400 | Malformed or invalid request-level input. | No. Fix the request. |
401 | Missing, expired, or invalid token. | Obtain a token and retry once. |
403 | Caller or source IP is not permitted. | No. Resolve access first. |
404 | Resource is unknown or not visible in this scope. | No. Check identifier and scope. |
422 | Validation or business precondition failed. | No unchanged retry. Fix data or state. |
429 | Rate limit exceeded. | Yes, after Retry-After. |
500 | Unexpected server error. | Yes, with backoff and the same idempotency key. |
Business failures
Do not retry unchanged when validation, permissions, balances, resource state, or another documented business precondition has failed. Correct the data or state before starting another attempt.
Retry an ambiguous state-changing request with the identical path, body, and
Idempotency-Key. Generate a new key only when starting a new operation.
Log the X-Request-Id, endpoint, method, status, response body, timestamp, and
environment for support investigation. Never log secrets or access tokens.