Get started
Errors
Use HTTP status codes for control flow, and keep all write operations idempotent.
HTTP status patterns
Error bodies include machine-readable fields and a human-readable message. Log both. Match HTTP class to your retry policy and surface user-facing copy from the message field.
| Status | Meaning | Retry? |
|---|---|---|
| 400 | Validation failure | No, fix the request |
| 401 | Missing/invalid credential | No |
| 403 | Forbidden / scope mismatch | No |
| 404 | Resource not found | No |
| 409 | Idempotency conflict / state conflict | Sometimes |
| 422 | Business-rule rejection | No |
| 429 | Rate limited | Yes, with backoff |
| 5xx | Xpend infrastructure | Yes, with backoff |
Typical error body
{
"error": {
"code": "validation_failed",
"message": "amount must be a positive decimal string",
"field": "amount",
"request_id": "req_01HXY..."
}
}Idempotency for writes
Treat every create endpoint as idempotent at the business-key level. Use one stable Idempotency-Key per business action.
- Log API request IDs and your idempotency keys.
- Other routes may be safe to retry at the business-rule layer.
- Make downstream operations idempotent by your own business key.
Webhook-specific behavior
Non-2xx responses on webhook deliveries trigger retry with exponential backoff. Make webhook consumers idempotent by event ID.
Heads up
An unexpected error occurred. Please try again., that's the canonical user-facing copy when the error envelope is missing a useful message, but you should always log the raw body for diagnostics.