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

# Blockra API Error Handling: Codes, Envelope & Examples

> Every Blockra API response uses a consistent envelope. Learn how to handle errors by HTTP status and error code with practical examples.

The Blockra API wraps every response in a consistent envelope so your error-handling logic stays uniform across all endpoints. On success, the `data` field is populated and `error` is `null`. On failure, `data` is `null` and `error` carries both a human-readable `message` and a stable machine-readable `code`.

## Response envelope

**Success response:**

```json theme={null}
{
  "data": { "id": "pay_a1b2c3d4e5f6g7h8i9j0k1l2" },
  "error": null
}
```

**Error response:**

```json theme={null}
{
  "data": null,
  "error": {
    "message": "Insufficient balance",
    "code": "INSUFFICIENT_BALANCE"
  }
}
```

<Note>
  Always check the HTTP status code first, then use `error.code` for programmatic branching and `error.message` for displaying a human-readable description to users.
</Note>

## Handling errors in code

<CodeGroup>
  ```ts Node.js theme={null}
  const res = await fetch("https://api.blockra.io/payments", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.BLOCKRA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ asset: "LTC", fiat_amount: 9.99 }),
  });

  const { data, error } = await res.json();

  if (!res.ok) {
    switch (error.code) {
      case "HTTP_401":
        throw new Error("Check your API key");
      case "HTTP_403":
        throw new Error("Key lacks required scope");
      case "RATE_LIMIT_EXCEEDED":
        // back off and retry
        break;
      default:
        throw new Error(error.message);
    }
  }

  // use data here
  ```

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

  res = requests.post(
      "https://api.blockra.io/payments",
      headers={"X-API-Key": os.environ["BLOCKRA_API_KEY"]},
      json={"asset": "LTC", "fiat_amount": 9.99},
  )

  body = res.json()

  if not res.ok:
      code = body["error"]["code"]
      if code == "HTTP_401":
          raise Exception("Check your API key")
      elif code == "RATE_LIMIT_EXCEEDED":
          pass  # back off and retry
      else:
          raise Exception(body["error"]["message"])

  data = body["data"]
  ```
</CodeGroup>

## Error codes

| HTTP | Code                   | Meaning                                                               |
| ---- | ---------------------- | --------------------------------------------------------------------- |
| 400  | `VALIDATION_ERROR`     | The request body or query string failed validation                    |
| 400  | `AMOUNT_TOO_SMALL`     | The amount is below the \$1 minimum, or the asset's payable precision |
| 401  | `HTTP_401`             | Missing, malformed, or invalid API key                                |
| 403  | `HTTP_403`             | Your key lacks the required scope for this endpoint                   |
| 404  | `NOT_FOUND`            | The resource does not exist or does not belong to your account        |
| 409  | `INSUFFICIENT_BALANCE` | Not enough available balance to complete a withdrawal                 |
| 429  | `RATE_LIMIT_EXCEEDED`  | Too many requests — back off and retry                                |
| 503  | `RATE_UNAVAILABLE`     | Live FX rate temporarily unavailable — retry shortly                  |
| 500  | `INTERNAL_ERROR`       | An unexpected error occurred on Blockra's side                        |

<Note>
  `VALIDATION_ERROR` responses also include a `details` array of per-field messages to help you pinpoint the offending input field.
</Note>

## Validation error example

```json theme={null}
{
  "data": null,
  "error": {
    "message": "Validation failed",
    "code": "VALIDATION_ERROR",
    "details": [
      { "field": "fiat_amount", "message": "fiat_amount is required" },
      { "field": "asset", "message": "asset must be one of BTC, LTC, ETH, USDC, USDT" }
    ]
  }
}
```