Blockra API Error Handling: Codes, Envelope & 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:

{
  "data": { "id": "pay_a1b2c3d4e5f6g7h8i9j0k1l2" },
  "error": null
}

Error response:

{
  "data": null,
  "error": {
    "message": "Insufficient balance",
    "code": "INSUFFICIENT_BALANCE"
  }
}

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.

Handling errors in code

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

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"]

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

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

Validation error example

{
  "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" }
    ]
  }
}

​Response envelope

​Handling errors in code

​Error codes

​Validation error example

Response envelope

Handling errors in code

Error codes

Validation error example