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

# Testing

Learn about error handling when using the API.

## Error Handling

The API uses standard HTTP status codes.

| Status | Description           |
| ------ | --------------------- |
| `200`  | Success               |
| `201`  | Resource created      |
| `400`  | Bad request           |
| `401`  | Unauthorized          |
| `403`  | Forbidden             |
| `404`  | Resource not found    |
| `409`  | Conflict              |
| `422`  | Validation error      |
| `429`  | Too many requests     |
| `500`  | Internal server error |

Example error response:

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "The amount must be greater than zero."
  }
}
```

## Transaction Failure Codes

When a transaction cannot be completed, the API returns a machine-readable failure code along with a human-readable message. Use these codes to determine the appropriate action for your application.

## Response Format

```json theme={null}

{
  "ok": false,
  "error": {
    "code": "string",
    "message": "string",
    "details": "string"
  }
}
```

## Failure Codes

| Failure Code            | Description                                                 | Recommended Action                                               |
| ----------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------- |
| `INSUFFICIENT_FUNDS`    | The customer does not have enough balance.                  | Ask the customer to top up their account and retry.              |
| `INVALID_ACCOUNT`       | The destination account or wallet does not exist.           | Verify the account details before retrying.                      |
| `INVALID_PHONE_NUMBER`  | The provided phone number is invalid.                       | Validate the phone number format.                                |
| `ACCOUNT_BLOCKED`       | The customer's account is blocked or suspended.             | Ask the customer to contact their provider.                      |
| `ACCOUNT_CLOSED`        | The destination account has been closed.                    | Request updated account information.                             |
| `PAYMENT_DECLINED`      | The payment was declined by the provider.                   | Inform the customer and allow another payment method.            |
| `PAYMENT_EXPIRED`       | The payment authorization expired before completion.        | Create a new payment request.                                    |
| `TRANSACTION_CANCELLED` | The customer cancelled the transaction.                     | Allow the customer to initiate a new payment.                    |
| `TRANSACTION_TIMEOUT`   | The provider did not respond within the expected time.      | Retry using an idempotency key.                                  |
| `DUPLICATE_TRANSACTION` | A transaction with the same idempotency key already exists. | Retrieve the existing transaction instead of creating a new one. |
| `LIMIT_EXCEEDED`        | The transaction exceeds provider or merchant limits.        | Reduce the amount or contact support.                            |
| `INVALID_AMOUNT`        | The requested amount is invalid.                            | Ensure the amount is within supported limits.                    |
| `INVALID_CURRENCY`      | The specified currency is not supported.                    | Use one of the supported currencies.                             |
| `MERCHANT_NOT_ACTIVE`   | The merchant account is inactive.                           | Contact KryptaPay Support.                                       |
| `PROVIDER_UNAVAILABLE`  | The payment provider is temporarily unavailable.            | Retry later with exponential backoff.                            |
| `NETWORK_ERROR`         | A network error occurred while processing the transaction.  | Retry the request safely.                                        |
| `INTERNAL_ERROR`        | An unexpected server error occurred.                        | Retry later or contact support if the issue persists.            |
| `COMPLIANCE_REJECTED`   | The transaction failed compliance or regulatory checks.     | Contact support for further guidance.                            |
| `FRAUD_SUSPECTED`       | The transaction was blocked by fraud detection systems.     | Do not retry automatically. Contact support if necessary.        |
| `UNKNOWN_ERROR`         | An unknown error occurred.                                  | Retry later or contact support.                                  |

## Best Practices

<Info>
  Always use the `failure_code` field for programmatic handling. The `failure_message` is intended for debugging and may change over time.
</Info>

<Warning>
  When retrying failed requests, always include the same `Idempotency-Key` to prevent duplicate transactions.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Going live" icon="globe-pointer" href="/going-live">
    Things to set to move from your sandbox account to live payments.
  </Card>
</CardGroup>