Skip to main content

​
Overview

BlockDB API uses structured error envelopes with consistent codes, HTTP status, retry guidance, and links back to the docs. Use hint, severity, and retryable to decide whether to fix the request or retry later.

​
Error Response Format

All error responses follow this structure (fields may vary by code): 
{
  "error": {
    "code": "ERROR_CODE",
    "http_status": 400,
    "message": "Human-readable error message.",
    "hint": "Actionable guidance.",
    "severity": "error | warning | critical",
    "retryable": false,
    "details": {},
    "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
  }
}

​
Common Error Codes

​
Authentication & Authorization

CodeHTTP StatusDescriptionResolution
BAD_REQUEST400Invalid or missing parametersFix fields listed in details.invalid_parameters; use ISO-8601 timestamps and valid chain IDs
UNAUTHORIZED401Invalid or missing API keySend Authorization: Bearer <API_KEY>; regenerate key if compromised
FORBIDDEN403API key lacks permission for this endpointUpgrade plan or request access (required_plan in details)
NOT_FOUND404Resource does not existVerify endpoint path and parameters
PAYLOAD_TOO_LARGE413Response would exceed size limitsLower limit, narrow block/time window, or reduce filters
RATE_LIMIT_EXCEEDED429Request rate exceededApply client throttling/backoff and honor retry_after_seconds
INTERNAL_SERVER_ERROR500Unexpected server errorSafe to retry; include incident_id in support tickets

​
Error Code Reference by Category

  • UNAUTHORIZED (401)
  • FORBIDDEN (403)
  • BAD_REQUEST (400)
  • NOT_FOUND (404)
  • RATE_LIMIT_EXCEEDED (429)
  • PAYLOAD_TOO_LARGE (413)
  • INTERNAL_SERVER_ERROR (500)

​
See Also