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

# Errors

> Understand the Minisend API error response structure, every HTTP status code your integration may receive, and how to handle each one in your code.

Every error response:

```json theme={null}
{ "error": "Description of what went wrong" }
```

One top-level `error` string. No nested objects.

## Status codes

| Status | Meaning                                                              |
| ------ | -------------------------------------------------------------------- |
| `400`  | Invalid request: missing required fields or invalid amount           |
| `401`  | Missing or invalid API key                                           |
| `403`  | Key valid, merchant account inactive                                 |
| `404`  | Session ID or merchant slug doesn't exist                            |
| `429`  | Rate limit: 60 req/min/IP. Response includes `X-RateLimit-Remaining` |
| `500`  | Transient server error. Retry with backoff                           |

### 400: Bad request

* `amount` must be a positive number, not a string, zero, or negative.
* For `POST /api/merchant/pay`, `amount` must be `0.01` to `10000`.

### 401: Unauthorized

* Header must be `Authorization: Bearer ms_live_...`.
* Verify the key in **API Keys**.

### 403: Forbidden

Key authenticated, but the merchant account is inactive. Contact support.

### 404: Not found

`session_id` (must start with `cs_`) or `slug` doesn't match any record.

### 429: Rate limit

Slow down. `X-RateLimit-Remaining` shows how close you are. Contact support for higher limits.

### 500: Server error

Retry with exponential backoff. If persistent, contact support with the `session_id` or request timestamp.

## Handling errors

<CodeGroup>
  ```javascript Node.js theme={null}
  const res = await fetch('https://merchant.minisend.xyz/api/merchant/checkout', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ms_live_your_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ amount: 25.00 }),
  });

  if (!res.ok) {
    const { error } = await res.json();

    if (res.status === 429) {
      await new Promise((r) => setTimeout(r, 2000));
    }

    throw new Error(`${res.status}: ${error}`);
  }

  const session = await res.json();
  ```

  ```python Python theme={null}
  import requests
  import time

  def create_checkout(amount):
      res = requests.post(
          "https://merchant.minisend.xyz/api/merchant/checkout",
          headers={"Authorization": "Bearer ms_live_your_key_here"},
          json={"amount": amount},
      )

      if not res.ok:
          if res.status_code == 429:
              time.sleep(2)
          raise RuntimeError(f"{res.status_code}: {res.json().get('error')}")

      return res.json()
  ```
</CodeGroup>