Errors & Troubleshooting

Response shape

Every non-2xx response returns JSON with a stable error code, the matching HTTP status, a human-readable message, and a request_id you can quote to support:

{
  "error": "tier_required",
  "message": "This endpoint requires Pro or Enterprise.",
  "request_id": "req_01HXY3Z9KFGT...",
  "details": null
}

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:

• invalid_key (401) — Check the Authorization header format. Key must start with verdict_pk_.
• expired_key (401) — Subscription expired. Renew at /dashboard/subscription.
• disabled_key (401) — Key was rotated or revoked. Generate a new one.
• tier_required (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.
• not_found (404) — Entity slug or UUID doesn't match any rated entity.
• validation_error (422) — Request body / query params failed validation; see details field for specifics.
• internal_error (500) — Server bug. Email support with the request_id.

The details field

For validation_error responses, the details field carries an array of per-field problems:

{
  "error": "validation_error",
  "message": "Request validation failed.",
  "request_id": "req_01HXY...",
  "details": [
    { "field": "skip", "message": "must be >= 0" },
    { "field": "limit", "message": "must be <= 100" }
  ]
}

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?).