Error Handling

https://api.cerulea.app/v1

All errors are returned with a consistent structure. The error.code field is stable across API versions and safe to branch on.

Error Response Format

JSON

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body failed validation",
    "details": [
      { "field": "consensus", "issue": "must be one of: poa, pos, dpos, pbft, raft" }
    ],
    "requestId": "req_01HXYZ456"
  }
}

Common Error Codes

HTTP Code	Error Code	Description
400	BAD_REQUEST	Invalid request parameters
401	UNAUTHORIZED	Invalid or missing authentication
403	FORBIDDEN	Insufficient permissions for the requested operation
404	NOT_FOUND	Resource not found
422	VALIDATION_ERROR	Request body failed validation
429	RATE_LIMITED	Rate limit exceeded, retry after the indicated delay
500	INTERNAL_ERROR	Internal server error

All 4xx errors are safe to handle deterministically. For 429, read the Retry-After header for the backoff delay. For 500, retry with exponential backoff, they are transient.