Common Errors

All error responses share a consistent outer structure. The request_id is always present — it's the first thing to grab when debugging:

{
  "error": {
    "code": "VALIDATION_ERROR",      // Machine-readable, always present
    "message": "query: Field required", // Human-readable description
    "details": [...]                    // Only on 422 responses
  },
  "request_id": "a1b2c3d4-..."        // Always present, even on 500s
}

Some older error paths use a flat format: {"error": "ValidationError", "message": "...", "request_id": "..."}. Both formats include request_id. In your error-handling code, check for error.code first, then fall back to error as a string.

A 400 response means the request was syntactically valid but semantically wrong. The platform understood your request format but rejected its content.

A 401 means the system could not identify the caller. No valid credentials were found across any of the supported authentication methods.

When the 401 is for API keys, the platform records a security audit event with a short key prefix and a failure reason. These entries are visible in the audit log under the api_key category and are useful for spotting repeated failed attempts.

A 403 means the system identified the caller but the caller lacks permission for the requested operation. Unlike 401, the credentials are valid — the authorization check failed.

A 422 means the request body failed schema validation. The response always includes a details array with per-field error information:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "messages → 0 → content: Field required",
    "details": [
      {
        "loc": ["body", "messages", 0, "content"],
        "msg": "Field required",
        "type": "missing"
      }
    ]
  },
  "request_id": "..."
}

Reading the loc path: The location array describes the path to the invalid field. ["body", "messages", 0, "content"] means "in the request body → the messages array → first element → the content field". The "body" prefix is always present and can be ignored.

Common validation errors:

• "Field required" — a mandatory field is missing from your request body
• "Input should be a valid string" — wrong data type (e.g., sending a number where a string is expected)
• "Value error, ..." — a custom business rule failed (the message after the prefix describes the rule)

A 429 means you've exceeded one of the three rate-limit layers (per-second, per-minute, or per-hour). The response tells you exactly which layer blocked you and when to retry:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded (per-minute). Try again in 12 seconds.",
    "limits": { "per_second": 10, "per_minute": 200, "per_hour": 5000 },
    "blocked_by": "per_minute",
    "retry_after": 12
  }
}

// Response headers:
// Retry-After: 12
// X-RateLimit-Limit: 200
// X-RateLimit-Remaining: 0
// X-RateLimit-Reset: 1715265600

How to handle in code:

1. Read the Retry-After response header — this is the number of seconds to wait
2. Check error.blocked_by to understand which layer is the bottleneck
3. If blocked_by is "per_second", add a small delay between requests (you're bursting too fast)
4. If blocked_by is "per_hour", you're hitting your budget limit — consider upgrading your plan tier

For a deep dive into rate limit tiers and response headers, see the Rate Limit Issues page.

A 500 is always a platform-side issue — never your fault as a caller. The response is intentionally minimal to avoid leaking internal details:

{
  "error": "InternalServerError",
  "message": "An unexpected error occurred",
  "request_id": "a1b2c3d4-e5f6-..."
}

What happens server-side: The full failure detail is recorded internally for post-mortem analysis. The request_id in the response correlates your error to that server-side record so support can investigate the exact failure.

What to do:

• Retry once — transient infrastructure issues can cause sporadic 500s
• Check GET /health — if a component is "unhealthy", wait for it to recover
• Contact support — include the request_id, the endpoint, the method, and the approximate timestamp