Errors and lifecycle

Treat transport failures, validation errors, and lifecycle outcomes differently. Never infer that funds moved from an HTTP timeout alone.

HTTP handling

Status	Action
`400`	Fix the request; do not retry unchanged input
`401` or `403`	Fix credentials or organization access
`404`	Check the resource ID and organization
`409`	Reuse the existing idempotent resource or requote
`422`	Route or amount is not executable; request a new quote later
`429`	Retry with backoff
`500` or `503`	Preserve the idempotency key and reconcile before retrying

Idempotency

Use one stable Idempotency-Key per logical payout or settlement order. A network retry uses the same key. A new customer action uses a new key.

Settlement errors

Settlement errors include stage, fundsStatus, fundsMoved, retryable, and nextAction. Follow those fields instead of parsing the human-readable message.

{
  "error": {
    "code": "QUOTE_EXPIRED",
    "message": "La cotizacion expiro.",
    "stage": "CREATED",
    "fundsStatus": "IN_USER_WALLET",
    "fundsMoved": false,
    "retryable": true,
    "nextAction": "CREATE_NEW_QUOTE"
  }
}

health: STUCK does not replace the order status. It means the order needs recovery while the status and fundsStatus continue to describe the last verified state.

Safe retry rule

Before resubmitting an onchain action, check the stored resource and transaction receipt. Never create a second burn, swap, or payout merely because the first HTTP request timed out.

Arc settlement

Review settlement stages and delivery boundaries.

API reference

Inspect response schemas and endpoint-specific status codes.

Start here

Products

Operations

HTTP handling

Idempotency

Settlement errors

Safe retry rule

Arc settlement

API reference

​HTTP handling

​Idempotency

​Settlement errors

​Safe retry rule

Arc settlement

API reference

HTTP handling

Idempotency

Settlement errors

Safe retry rule