- The HTTP status (4xx / 5xx).
- An error envelope in the body.
error.message is usually a string, but for validation errors (400) it can be an
array of messages. error.code is specific for authentication and quota
errors; for validation and not-found it is INTERNAL_ERROR and the HTTP status
carries the meaning.
HTTP status reference
Authentication errors (401)
API_KEY_REQUIRED
API_KEY_REQUIRED
No
X-API-Key header was sent. Every /openapi/v1/* request requires one.API_KEY_INVALID
API_KEY_INVALID
The key is unknown or malformed. Check for stray whitespace or a truncated
value.
API_KEY_DISABLED
API_KEY_DISABLED
The key has been revoked. Create a new one in the dashboard.
API_KEY_EXPIRED
API_KEY_EXPIRED
The key has expired. Create a new one in the dashboard.
Authorization & quota errors
FEATURE_NOT_IN_PLAN (403)
FEATURE_NOT_IN_PLAN (403)
Your subscription plan doesn’t include the requested data domain. Upgrade
from the dashboard — see Plans & features.
RATE_LIMIT_EXCEEDED (429)
RATE_LIMIT_EXCEEDED (429)
You’ve consumed your plan’s per-minute weight budget. Wait until
X-RateLimit-Reset (or Retry-After seconds) then retry — see
Rate limits.Validation & not-found (400 / 404)
Missing or invalid parameter (400)
Missing or invalid parameter (400)
A required query parameter is missing or a value is out of range.
error.message
lists the specific problems, e.g. "Type parameter is required".Resource not found (404)
Resource not found (404)
The path references something that doesn’t exist (e.g. an unknown commodity
slug or fund code).
Handling strategy
1
Check the HTTP status first
2xx → read data. 4xx / 5xx → read error.code to classify.2
Retry only the right cases
Retry with backoff on
429 (until Retry-After / X-RateLimit-Reset) and
5xx (exponential backoff, a few attempts). Do not retry 400, 401 or
403 — fix the root cause first.3
Log enough context
Capture
error.code, error.message, meta.timestamp, the HTTP status and
the request path when reporting an issue.