Blockra API Error Handling: Codes, Envelope & Examples - Blockra

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": "Payment not found",
    "code": "NOT_FOUND"
  }
}

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/checkout/sessions", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.BLOCKRA_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount: 9.99, currency: "USD" }),
});

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/checkout/sessions",
    headers={"X-API-Key": os.environ["BLOCKRA_API_KEY"]},
    json={"amount": 9.99, "currency": "USD"},
)

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 $0.10 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
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": "amount", "message": "amount is required" },
      { "field": "currency", "message": "currency must be one of USD, EUR, GBP" }
    ]
  }
}