> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simplepay.mx/llms.txt
> Use this file to discover all available pages before exploring further.

# Handle API errors

> Interpret stable codes, request IDs, and retryable responses.

Public errors include a stable code and `request_id`. Use the code for decisions and the request ID for support.

## Classify the response

| Status | Meaning                                          | Action                     |
| ------ | ------------------------------------------------ | -------------------------- |
| `400`  | Invalid payload or parameter                     | Correct the request        |
| `401`  | Missing or invalid credential                    | Check host and key         |
| `403`  | Missing scope or capability                      | Check permissions          |
| `404`  | Resource absent in this merchant and environment | Check the ID               |
| `409`  | State, readiness, or idempotency conflict        | Read `code`                |
| `429`  | Limit exceeded                                   | Honor `Retry-After`        |
| `5xx`  | Temporary dependency failure                     | Retry only idempotent work |

Log `request_id`, method, route, status, and code. Do not log keys, full financial payloads, or personal data.

`capability_not_enabled` means the product is not granted. `capability_not_ready` means a granted product lacks temporary readiness.