Skip to main content

​
Error Response Formats

Errors have two shapes depending on the source: Auth/middleware errors (401, 403, 429): 
{
  "error": "ERROR_CODE",
  "message": "Human-readable description"
}
Handler errors (400) — when a handler returns success: false: 
{
  "error": "error message from handler",
  "meta": {
    "latencyMs": 45,
    "freshness": "live",
    "source": "morpho"
  }
}

​
Error Codes

​
Authentication (401)

CodeDescription
MISSING_API_KEYNo Authorization: Bearer header provided
INVALID_KEY_FORMATKey present but wrong prefix (must start with circ_live_ or circ_test_)
INVALID_API_KEYAPI key not found or revoked
UNAUTHORIZEDNo Bearer token provided on a JWT-authenticated route
INVALID_TOKENJWT is malformed, expired, or signature invalid

​
Authorization (403)

CodeDescription
ACCOUNT_SUSPENDEDAccount billing is suspended. Contact support to reactivate
FORBIDDENJWT does not have the required role
ENDPOINT_NOT_INCLUDEDYour tier does not include this endpoint category. Response includes upgrade: true

​
Rate Limiting (429)

CodeExtra FieldsDescription
RATE_LIMIT_EXCEEDEDretryAfter (seconds)Sliding window rate limit hit
DAILY_QUOTA_EXCEEDEDlimit, usedDaily request quota exhausted
MONTHLY_QUOTA_EXCEEDEDlimit, usedMonthly request quota exhausted

​
Handler Errors (400)

When a handler returns success: false, the API responds with the error message and metadata. These are domain-specific errors like invalid parameters or missing data.

​
Circuit Breaker (503)

When an upstream dependency is unavailable: 
{
  "error": "Service temporarily unavailable",
  "retryAfterMs": 30000
}
The circuit breaker opens after repeated failures to an upstream provider (Morpho, Aave). It auto-closes after the retryAfterMs window.

​
Internal Errors (500)

Unhandled exceptions return a generic error. Stack traces are included only in non-production environments. 
{
  "error": "Internal server error"
}

​
Not Implemented (501)

When a requested feature is not yet available: 
{
  "error": "Not yet implemented",
  "detail": "SSE transport is not yet implemented"
}