| Code | Status | Detail |
|---|---|---|
invalid_value | 400 | A request value is invalid. |
unauthenticated | 401 | Authentication is required. |
forbidden | 403 | You do not have permission to perform this action. |
external_account_not_found | 404 | External account not found. |
payment_not_found | 404 | Payment not found. |
recipient_agent_not_found | 404 | The specified recipient agent does not exist. |
already_exists | 409 | The resource already exists. |
conflict | 409 | The request conflicts with the current resource state. |
customer_wallet_required | 409 | A customer wallet is required before creating this payment. |
external_account_not_verified | 409 | External account must be verified before it can be used. |
insufficient_funds | 409 | Insufficient funds. |
payment_failed | 409 | Payment failed. |
recipient_agent_not_eligible | 422 | The specified recipient agent is not eligible to receive wallet-backed payments. |
recipient_not_eligible | 422 | The selected recipient is not yet eligible to receive wallet-backed payments. |
rate_limited | 429 | Too many requests. |
server_error | 500 | Something went wrong. |
bad_gateway | 502 | We couldn’t complete that request because one of Natural’s services returned an unexpected response. Please try again. |
service_unavailable | 503 | The service is temporarily unavailable. |
Resource errors
Payments
Public error codes for Payments API endpoints
All error responses follow the standard error format.
Validation errors (422) and rate limit errors (429) apply to all endpoints and are documented in the Error Handling guide.