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

# Errors

> Understand Pasteaza API error responses and status codes.

Pasteaza uses standard HTTP status codes and consistent error responses so you can understand what went wrong and handle failures in your application.

<Info>
  Always check the HTTP status code first. Then use the error `code` field for programmatic handling.
</Info>

## Error response format

```json theme={null}
{
  "status": false,
  "message": "Invalid API key.",
  "code": "authentication_failed"
}
```

## Common HTTP status codes

| Status code | Meaning                          |
| ----------- | -------------------------------- |
| `200`       | Request completed successfully   |
| `201`       | Resource created successfully    |
| `400`       | Bad request or validation error  |
| `401`       | Authentication failed            |
| `403`       | Permission denied                |
| `404`       | Resource not found               |
| `409`       | Duplicate or conflicting request |
| `429`       | Too many requests                |
| `500`       | Server error                     |

## Common error codes

| Code                           | Meaning                                                                                                             |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `authentication_failed`        | The API key is missing, invalid, or inactive.                                                                       |
| `validation_failed`            | One or more required fields are missing or invalid. Validation errors usually return HTTP `400` in the current API. |
| `invalid_test_bank`            | The supplied test bank code is invalid. In test mode, use the supported test bank code.                             |
| `recipient_not_found`          | The supplied `recipientCode` was not found for the authenticated merchant and environment.                          |
| `insufficient_balance`         | The merchant does not have enough available balance for the transfer.                                               |
| `transfer_not_found`           | The requested transfer reference was not found.                                                                     |
| `virtual_account_not_found`    | The requested virtual account reference was not found.                                                              |
| `provider_incomplete_response` | The upstream provider returned incomplete virtual account details.                                                  |
| `provider_request_failed`      | The upstream provider request failed.                                                                               |

## Validation error example

```json theme={null}
{
  "status": false,
  "message": "amount must be a positive integer.",
  "code": "validation_failed"
}
```

## How to handle errors

<Steps>
  <Step title="Check the status code">
    Use the HTTP status code to decide whether the request failed because of authentication, validation, permission, or server issues.
  </Step>

  <Step title="Read the error code">
    Use the `code` field for app logic and retry decisions.
  </Step>

  <Step title="Show a helpful message">
    Use the `message` field to display a friendly explanation to the user.
  </Step>

  <Step title="Retry safely">
    Retry only safe requests or requests that include an `Idempotency-Key`.
  </Step>
</Steps>

## Best practices

* Log the status code, error code, and request reference when a request fails.
* Do not expose raw server messages to end users without context.
* Retry only when the request is safe to repeat.
* Use idempotency for create and payout requests.
* Contact support if you repeatedly receive `server_error` responses.

## Next step

After you understand errors, continue with webhooks so you can verify asynchronous updates from Pasteaza.