Error Codes

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

Code	HTTP Status	Description	Resolution
`BAD_REQUEST`	400	Invalid or missing parameters	Fix fields listed in `details.invalid_parameters`; use ISO-8601 timestamps and valid chain IDs
`UNAUTHORIZED`	401	Invalid or missing API key	Send `Authorization: Bearer <API_KEY>`; regenerate key if compromised
`FORBIDDEN`	403	API key lacks permission for this endpoint	Upgrade plan or request access (`required_plan` in `details`)
`NOT_FOUND`	404	Resource does not exist	Verify endpoint path and parameters
`PAYLOAD_TOO_LARGE`	413	Response would exceed size limits	Lower `limit`, narrow block/time window, or reduce filters
`RATE_LIMIT_EXCEEDED`	429	Request rate exceeded	Apply client throttling/backoff and honor `retry_after_seconds`
`INTERNAL_SERVER_ERROR`	500	Unexpected server error	Safe to retry; include `incident_id` in support tickets

Error Code Reference by Category

Authentication & Authorization

UNAUTHORIZED (401)
FORBIDDEN (403)

Request Validation

BAD_REQUEST (400)
NOT_FOUND (404)

Quota & Payload

RATE_LIMIT_EXCEEDED (429)
PAYLOAD_TOO_LARGE (413)

Server Errors

INTERNAL_SERVER_ERROR (500)

Overview

SDKs

Account & Usage

EVM Endpoints

Enumerations

Overview

Error Response Format

Common Error Codes

Authentication & Authorization

Error Code Reference by Category

See Also

​Overview

​Error Response Format

​Common Error Codes

​Authentication & Authorization

​Error Code Reference by Category

​See Also

Overview

Error Response Format

Common Error Codes

Authentication & Authorization

Error Code Reference by Category

See Also