# 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             |


---

# 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://startbutton.gitbook.io/startbutton-product-api/startbutton-api-doc/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.