> For the complete documentation index, see [llms.txt](https://startbutton.gitbook.io/startbutton-product-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://startbutton.gitbook.io/startbutton-product-api/startbutton-api-doc/errors.md).

# Errors

When a request to the Startbutton API fails, the response provides clear details on what went wrong and how to resolve it. Each error follows a consistent structure, including a human-readable message, a machine-readable error code, and optional diagnostic information to support quick debugging.

As a RESTful API, Startbutton uses standard HTTP response codes to indicate whether a request was successful or failed.

### HTTP Codes

| Status  | Typical use                                                                             |
| ------- | --------------------------------------------------------------------------------------- |
| **400** | Bad request (invalid input, business rule failure)                                      |
| **401** | Unauthorized (invalid/expired auth, invalid secret/integration key, merchant not found) |
| **403** | Forbidden (IP not allowed, role/team, KYC restrictions)                                 |
| **404** | Not found (resource/merchant/invoice/transaction not found)                             |
| **409** | Conflict (e.g. duplicate recipient, “Invoice Recipient already exists”)                 |
| **422** | Validation error (e.g. invalid `lastUpdatedBy` in query-transactions)                   |
| **429** | Rate limit exceeded                                                                     |
| **500** | Internal server / generic error                                                         |

### FX rates

| Code                      | Meaning                 |
| ------------------------- | ----------------------- |
| `RATE_NOT_AVAILABLE`      | Rate not available      |
| `RATE_ZERO`               | Rate is zero            |
| `CURRENCY_PAIR_NOT_FOUND` | Currency pair not found |

### Transfers

| Code                            | Meaning                                                  |
| ------------------------------- | -------------------------------------------------------- |
| `INSUFFICIENT_BALANCE`          | Transfer/refund failed due to low available balance      |
| `FAILED_TO_CREATE_RECIPIENT`    | Recipient creation failed (transfer/refund)              |
| `INVALID_BANK_CODE`             | Invalid bank code (defined in enum; rarely set in flows) |
| `UNEXPECTED_ERROR`              | Generic unexpected error                                 |
| `DUPLICATE_PROVIDER_REFERENCE`  | Duplicate reference from provider                        |
| `NO_AVAILABLE_PAYMENT_PARTNERS` | No payout partner available for the transfer             |