Errors

Failed requests return an HTTP status code and a single error object. Branch on the status code and on error.type; error.message is for people and may change.

Shape

400 Bad Requestjson

{
  "error": {
    "type": "invalid_request",
    "message": "amount must be a positive integer in cents.",
    "request_id": "0HN7KQ4F1V2C3:00000001"
  }
}

error.typestring

Stable category, see the table below

error.messagestring

Human-readable explanation. Server errors always say Unexpected error.

error.request_idstring

Send it to support when you need help with a specific call

Types

invalid_request400

Malformed JSON, missing or invalid field, amount above your per-charge limit, insufficient balance for a payout

authentication_failed401

Missing or wrong client_id / api_key, or an invalid Armhed-Operation-Token

forbidden403

Your IP is not in the allowlist, or the account is not approved for this operation

not_found404

The charge or payout does not exist on your account

conflict409

The identifier matches more than one payout, or the idempotency key is already being processed

rate_limited429

Too many requests; slow down and retry

unavailable503

The settlement route is temporarily down; retry later

server_error500

Unexpected error on our side

Retrying safely

Send an Idempotency-Key header on every POST (it is required for payouts). Retrying with the same key never creates a second charge or payout: you get the original back. Retry on network errors, 429, 500 and 503 with growing delays; do not retry other 4xx without changing the request.