Errors & Troubleshooting

Response shape

Every non-2xx response nests the error envelope under a detail object: a stable error code, the matching HTTP status, a human-readable message, and a docs_url. Quote the response request_id in any support email:

{
  "detail": {
    "error": "tier_insufficient",
    "message": "This endpoint requires the pro tier.",
    "docs_url": "https://verdict.finance/docs#error-tier_insufficient"
  }
}

The request_id survives across all logs. Include it in any support email and we can trace the request end-to-end.

Error codes

The common codes you'll see:

• missing_key (401) — No Authorization header. Send Authorization: Bearer <key>.
• invalid_key (401) — A key that matches no row. API keys start with verdict_pk_; credentials in other formats fall through to the platform's other auth.
• disabled_key (401) — Key was rotated or revoked. Generate a new one.
• tier_insufficient (403) — Endpoint requires Pro or Enterprise. Upgrade at /dashboard/subscription.
• rate_limit_exceeded (429) — Wait until X-RateLimit-Reset epoch; Pro tier has 1,000 req/min.
• export_daily_limit (429) — Bulk export cap of 5/day (rolling 24h) is full. Retry after the Retry-After header; X-RateLimit-Reset is when your oldest export leaves the window. Successful exports carry X-Export-Limit and X-Export-Remaining.
• not_found (404) — Entity slug or UUID doesn't match any rated entity.
• validation_error (422) — Request body / query params failed validation; see the errors array for specifics.
• internal_error (500) — Server bug. Email support with the request_id.

The errors array

For validation_error responses, the nested detail.errors field carries the array of per-field problems (FastAPI's validation format):

{
  "detail": {
    "error": "validation_error",
    "message": "Request validation failed",
    "errors": [
      { "loc": ["query", "limit"], "msg": "Input should be less than or equal to 100", "type": "less_than_equal" }
    ],
    "docs_url": "https://verdict.finance/docs#error-validation_error"
  }
}

Handling 429 (rate limit)

When you hit the rate limit, the response carries X-RateLimit-Limit, X-RateLimit-Remaining (will be 0 on a 429), and X-RateLimit-Reset (epoch seconds). Sleep until the reset epoch then retry. See Rate Limits & Usage for a backoff pattern.

Contacting support

For internal_error or any unexpected behaviour, email support@verdict.finance with:

• The full request_id.
• The endpoint and timestamp (UTC).
• Any obvious reproduction steps (single endpoint? batch?).