Errors

#Success and error payloads

Structured errors return JSON of the form:

{
  "detail": {
    "error_code": "SOME_CODE",
    "message": "Human-readable explanation."
  }
}

Validation errors (error_code: "VALIDATION_ERROR") additionally include a fields array describing each rejected input. Each entry has type (a stable code such as missing, extra_forbidden, int_parsing, string_too_long), loc (path to the field), msg (human text), and input (the value that failed). Use detail.message for a single-line summary and detail.fields if you need per-field structured detail.

Authentication failures use the same object form: 401 AUTH_API_KEY_MISSING (no X-API-Key), 403 AUTH_API_KEY_INVALID (unknown or inactive key), 403 AUTH_USER_INACTIVE, 403 AUTH_EMAIL_NOT_VERIFIED. Every 4xx and 5xx response uses the object form above.

An error returned after credits were debited also carries credits_used, the credits that request used.

Plan-tier responses. A request may be rejected because the caller's plan does not include the requested endpoint or option. These return 403 with one of PLAN_TIER_INSUFFICIENT, PLAN_TIER_INSUFFICIENT_HISTORY, PLAN_TIER_INSUFFICIENT_FORMULA_OVERRIDE, or PLAN_TIER_INSUFFICIENT_COVERAGE. The detail body also carries required_tier (the lowest plan that would accept the request) and current_tier (the caller's current plan). See API key, account, and plan errors.

#API key, account, and plan errors

Every PLAN_TIER_* response includes required_tier and current_tier strings (lowercase plan names) in the detail body so clients can prompt for an upgrade without parsing the message text.

#Request limits (validation)

These caps apply at validation time (422 when exceeded):

AkkruData — API user guide.