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": {
    "legalAddress": {
      "country": [
        {
          "code": "invalid_country",
          "message": null,
          "params": { "value": "INVALID" }
        }
      ]
    }
  }
}

Field	Meaning
`code`	HTTP status code as a number.
`message`	Human-readable summary; its wording can change.
`errors`	Validation or request-level details, or `null` when none is available.

Validation details follow the field structure: leaf fields contain arrays of errors, nested fields contain objects, and array items use objects keyed by index, such as "0". Do not assume field paths are flattened into dotted keys.

Request-level failures can instead contain details such as "errors": { "message": "Failed to parse the request body as JSON" }. Business rejections can have errors: null, with the reason in message.

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.
`409`	Request conflicts with an existing resource or operation.	No unchanged retry. Resolve the conflict or retrieve the existing resource.
`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.

For Client Trade onboarding, a new request using an existing partnerClientId returns 409 Conflict. Retrieve the existing onboarding case instead. Retrying the original request with its original Idempotency-Key returns the original result.

Retry an ambiguous state-changing request with the identical path, body, and Idempotency-Key. Generate a new key only when starting a new operation.

Safe diagnostics

Log X-Request-Id, the endpoint template, method, HTTP status, timestamp, and environment for support investigation. Allowlist safe field paths and machine-readable error codes when more detail is needed.

Do not log raw request or response bodies. Validation errors can echo submitted values in params.value, and messages may contain sensitive data. Redact party details, account numbers, document content, secrets, and access tokens before sending diagnostics to logs or support systems.

Error shape

Status handling

Business failures

Safe diagnostics

On this page