Error Response Format

When a request fails, the API returns a JSON error response with an appropriate HTTP status code:

{
  "error": {
    "message": "Validation failed: amount must be greater than 0",
    "code": "validation_error",
    "details": {
      "field": "amount",
      "reason": "must be greater than 0"
    }
  }
}

The error object contains:

message -- A human-readable description of what went wrong
code -- A machine-readable error code (e.g., validation_error, insufficient_balance, rate_limit_exceeded)
details -- Additional context, present for validation errors and other cases where field-level detail is available

HTTP Status Codes

Client Error Codes (4xx)

Code	Meaning	What to Do
`400`	Bad Request	Check the message and details fields. Fix the request and retry.
`401`	Unauthorized	Check your Authorization header. Ensure the key is not revoked.
`403`	Forbidden	Your key does not have access to this resource or action.
`404`	Not Found	Check the ID in your URL. The resource may have been deleted.
`409`	Conflict	State conflict (e.g., cancelling a completed payout). Check current status.
`422`	Unprocessable Entity	Valid JSON but semantically wrong. Check field values.
`429`	Too Many Requests	Rate limit exceeded. Back off and retry after the Retry-After header value.

Server Error Codes (5xx)

Code	Meaning	What to Do
`500`	Internal Server Error	Retry with exponential backoff. Contact support if persistent.
`502`	Bad Gateway	Upstream service unavailable. Retry in a few seconds.
`503`	Service Unavailable	Retry with backoff. Check the status page.

Retry Strategies

Not all errors should be retried. Follow these guidelines:

Never retry 4xx errors (except 429) -- These indicate a problem with your request that will not be fixed by retrying. Fix the request first.
Always retry 429 responses -- Use the Retry-After header to determine how long to wait.
Retry 5xx errors with exponential backoff -- Start with a short delay (e.g., 1 second) and double it with each attempt. Add random jitter to avoid thundering herd problems. Cap at a maximum number of retries (e.g., 5 attempts).

Example Error Handling

curl https://api.antonpayments.dev/v1/payouts \
  -X POST \
  -H "Authorization: Bearer ak_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pay-inv-1042" \
  -d '{
    "payee_id": "pye_abc123",
    "amount": "500.00",
    "currency": "USD"
  }'

If this returns a 422, check the error.details field for which field failed validation. If it returns a 429, read the Retry-After header and wait that many seconds before retrying. If it returns a 500, retry with exponential backoff using the same Idempotency-Key to prevent duplicate payouts.

Common Error Codes

validation_error -- One or more request fields are invalid
insufficient_balance -- Not enough funds in the specified currency to complete the operation
rate_limit_exceeded -- Too many requests in the current time window
resource_not_found -- The specified resource does not exist
state_conflict -- The resource cannot transition to the requested state
idempotency_conflict -- An idempotency key was reused with a different request body