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

# Error Codes & Troubleshooting

> Comprehensive guide to error codes and resolutions

# Error Codes & Troubleshooting

Handle uses standard HTTP status codes along with granular error codes in the response body to help you diagnose and handle issues.

## Error Response Format

```json theme={null}
{
  "status": "error",
  "code": "NO_ACTIVE_MANDATE",
  "message": "The customer has no active bank mandate on Handle."
}
```

***

## Status Code & Error Matrix

| HTTP Status             | Error Code              | Description & Developer Action                                                                                        |
| :---------------------- | :---------------------- | :-------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized`      | `UNAUTHORIZED`          | Invalid, expired, or missing `sk_live_...` / `sk_test_...` key. Verify your Authorization header.                     |
| `404 Not Found`         | `HANDLE_NOT_FOUND`      | The `@handle` or phone number is not registered on Handle. Prompt user to check spelling or sign up.                  |
| `400 Bad Request`       | `NO_ACTIVE_MANDATE`     | Customer has no active bank account mandate. Prompt customer to activate their bank mandate in the Handle mobile app. |
| `409 Conflict`          | `DUPLICATE_REFERENCE`   | The `reference` has already been used. Generate a fresh unique reference for new charges.                             |
| `400 Bad Request`       | `USER_DECLINED`         | The customer explicitly tapped **Decline** on their in-app push notification prompt.                                  |
| `402 Payment Required`  | `INSUFFICIENT_FUNDS`    | The customer's bank rejected the debit due to insufficient balance.                                                   |
| `408 Request Timeout`   | `AUTHORIZATION_TIMEOUT` | Customer did not approve the push prompt within the 3-minute window. Allow customer to retry.                         |
| `429 Too Many Requests` | `RATE_LIMITED`          | Exceeded API rate limits. Implement exponential backoff and respect the `Retry-After` header.                         |
| `500 Server Error`      | `INTERNAL_SERVER_ERROR` | An unexpected error occurred on Handle. Contact support if this persists.                                             |