Skip to main content

​
Error Classes

Common status patterns:
  • 400: malformed request shape or unsupported inputs
  • 401: missing/invalid API key for protected requests
  • 404: resource not found (conversation/run/source IDs)
  • 422: validation failure (schema/query constraints)
  • 429: rate limit exceeded (Retry-After returned)
  • 5xx: provider/runtime failure path

​
Error Payload Shapes

Most endpoints return JSON with a detail field. Career recommendation validation/error endpoints return RFC7807-style payloads (application/problem+json) with fields such as:
  • title
  • status
  • detail
  • instance
  • optional errors

​
Retry Guidance

​
429 rate limiting

  • Respect Retry-After header.
  • Use exponential backoff with jitter for client retries.
  • Avoid parallel burst retries from the same client identity.

​
5xx transient failures

  • Retry idempotent reads first (GET endpoints).
  • For writes, only retry when endpoint semantics are idempotent in your client flow.

​
Ingestion-specific errors

  • Relevance gate LLM failure - Returns status: "error" with rejection_reason containing “LLM call failed; rejected (fail closed)”. This is deterministic - the same source will fail again until the provider recovers. Do not retry blindly; check provider status via /api/stats/providers first.
  • Concurrent duplicate - Returns error with message “Ingestion already in progress for ”. Wait for the first ingestion to complete before retrying.
  • Partial pipeline failure - Chunks are rolled back automatically. Job transitions to failed. Safe to re-ingest after the underlying issue is resolved.

​
Streaming (/api/chat/stream)

  • Treat error as terminal for that stream.
  • Reconnect with a fresh stream request instead of resuming partial SSE output.

​
Client Safety Rules

  • Do not assume HTTP 200 implies complete success for every ingestion mode.
  • For direct ingestion paths, inspect response body status fields.
  • Always log response body + X-Response-Time + request ID/correlation IDs in operators.