Reference

Errors use a consistent envelope. Use error.code for programmatic handling and include meta.request_id when contacting support.

{
  "error": {
    "code": "not_found",
    "message": "invoice not found"
  },
  "meta": {
    "request_id": "req_0000000000000001"
  }
}

Usage

Handle retryable and non-retryable errors separately.

curl https://api.halfin.xyz/api/v1/invoices/00000000-0000-0000-0000-000000000001 \
  -H "X-API-Key: $HALFIN_API_KEY"

try {
  // Call a generated SDK method here.
} catch (error) {
  console.error(error);
}

# Python SDK coming soon. Use the cURL example for now.

Always include meta.request_id in support tickets so on-call can find the trace immediately.

401 means missing or invalid credentials.

403 means valid credentials without the required permission.

503 gate_offline means a blockchain processor is temporarily unavailable.