# Error handling and retries

Interpret structured API errors and retry only temporary or ambiguous failures.

Product: Client Trade API
Guides follow API reference 0.3.0 and event reference 0.2.0.
Canonical page: https://docs.axiym.io/trade-api/integration-guide/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

```json
{
  "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.