# Errors

Nexterpay uses standard HTTP status codes. Response bodies for errors typically contain a machine-readable code and a human-readable message.

## HTTP status codes

| Code               | Meaning            | Typical cause                                                    |
| ------------------ | ------------------ | ---------------------------------------------------------------- |
| `200 OK`           | Success            | Request completed.                                               |
| `201 Created`      | Resource created   | Order or sender accepted.                                        |
| `400 Bad Request`  | Validation error   | Missing field, invalid country/operator, duplicate `externalID`. |
| `401 Unauthorized` | Auth problem       | Token missing, malformed, or expired.                            |
| `404 Not Found`    | Resource not found | `externalID` or `orderID` does not exist on Nexterpay.           |

## Error response shape

```json
{
  "error": "ExternalIDAlreadyExists",
  "message": "An order with this externalID has already been submitted."
}
```

## Diagnose a failed transaction

When a PayIn or PayOut transitions to `validationStatus: Failed`, fetch the underlying reason with:

```
GET /Errors/GetOrderErrors?orderID=UUID
```

```bash
curl "https://api-sandbox.nexterpay.io/Errors/GetOrderErrors?orderID=c9a1f8e0-4b3c-4b9e-8a2d-5e6f7a8b9c0d" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

```json
[
  {
    "code": "INSUFFICIENT_FUNDS",
    "message": "The customer's Mobile Money wallet has insufficient balance.",
    "timestamp": "2026-04-23T10:16:05Z"
  }
]
```

This is the **only endpoint in v1.0 that uses `GET`** — the rest use `POST`.

## Common errors and fixes

| Error                                       | Cause                                                                 | Fix                                                                                                |
| ------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `External ID already exists`                | Reusing an `externalID` on a new transaction.                         | Generate a fresh `externalID`. If you are retrying after a timeout, call `Get…ByExternalID` first. |
| `Token has expired`                         | Bearer token past its lifetime (600 min sandbox / 90 min production). | Request a new token via `/security/createToken`.                                                   |
| `Invalid postalCode` / missing `postalCode` | `AddPayOutSender` without `postalCode`.                               | Always include `postalCode`. For Cameroon, `00237` is a safe default.                              |
| `Invalid operator`                          | Operator name mis-cased or unsupported in country.                    | Fetch the list via `/Catalog/GetMMOperators?countryCode=XX` and use the exact string returned.     |
| `Insufficient funds` (PayOut)               | Wallet balance below payout amount.                                   | Call `/Ledger/GetLedgerBalance` before payout. Top up your wallet.                                 |
| `Invalid currency for country`              | Submitted currency does not match country's default.                  | For Cameroon, use `XAF`. Confirm via `/Catalog/GetCountries`.                                      |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nexterpay.io/platform/errors.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.