Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

Errors and debugging

Handle QuiverAI API errors, correlate request IDs, inspect Logs, and escalate persistent failures.

QuiverAI API failures use standard HTTP statuses and a machine-readable JSON envelope:

{
  "status": 429,
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Branch on status and code, not on the human-readable message.

Status and code guide

Status Common codes What to do
400 invalid_request Correct missing, malformed, or incompatible parameters. Do not retry the same body unchanged.
401 invalid_api_key, unauthorized Check the Bearer header, secret, key status, environment, project, and key authority.
402 insufficient_credits, funding_pending, funding_payment_method_required, funding_payment_action_required, funding_payment_failed Resolve funding in API Platform Billing, then retry when the balance or payment action is settled.
403 unauthorized, account_frozen, content_policy_violation, invalid_request Check the key’s allowed operations and models, then resolve any account, content-policy, or endpoint-specific restriction.
404 model_not_found or invalid_request Refresh GET /v1/models for model availability and verify the endpoint path.
408 or 504 request_timeout Treat the outcome as potentially uncertain. Before retrying, assess duplicate-work risk; Responses has no documented idempotency key.
413 payload_too_large Reduce the upload or request payload before retrying.
429 rate_limit_exceeded, operation_rate_limit_exceeded, weekly_limit_exceeded Respect Retry-After when present, add backoff and jitter, and review Limits.
500 server_error Before retrying, assess duplicate-work risk; Responses has no documented idempotency key. Escalate persistent failures.
502 model_error Before retrying, assess duplicate-work risk; Responses has no documented idempotency key. Escalate persistent failures.
503 model_unavailable Before retrying, assess duplicate-work risk; Responses has no documented idempotency key. Escalate persistent failures.

Correlate a request

Every response includes X-Request-ID. On an error response, it matches the envelope’s request_id. Record this value with the endpoint, model, status, code, and UTC timestamp.

You can also send an optional x-trace-id from your application. The API echoes it in X-Trace-ID, letting you join QuiverAI request records with caller telemetry.

When request metadata is available under your data policy, use Logs to inspect the request outcome. Logs can help correlate a request with its project, API key, endpoint, model, status, charge state, and public error code; they do not capture prompts, request or response bodies, uploads, or generated artifacts.

Interpret a rate-limit response

A 429 means an independently enforced capacity rejected the request. Use the canonical response-header definitions to interpret the reported scope, subject, dimension, remaining capacity, reset time, and optional Retry-After.

A key that does not authorize the requested operation or model can reject with 403 unauthorized. Check its allowed operations and models in API Keys; changing capacity settings does not grant a key additional authority.

Honor Retry-After when it is present. When no retry timing is supplied and the reported capacity is zero, the relevant limit must change before the request can succeed.

Unsupported Responses options

The Responses endpoint is stateless. store: true and a non-null previous_response_id return 400 invalid_request before model execution, regardless of organization policy. Omit store or send false; omit previous_response_id or send null. Continue by replaying the full input history, not by retrieving a stored response. Changing data policy will not enable these features.

Remove unsupported fields such as background, include, and websocket before retrying. See Current limitations. Caller-tool storage is your application’s responsibility and is distinct from QuiverAI’s metadata and inference-retention policies in Data controls.

Streaming failures

Handle each failure boundary separately:

  • HTTP setup failure: A non-200 response before SSE begins uses the JSON error envelope.
  • Terminal SSE failure: For /v1/responses, handle response.failed, response.incomplete, and event: error. Collect complete function_call or custom_tool_call items before handling them; partial arguments are not executable calls. A completed call can be followed by more refinement turns, so do not publish staged content until the tool loop finishes successfully.
  • Early EOF: If the connection closes before a recognized terminal event, treat the outcome as uncertain and retain the request id for investigation.
  • Client cancellation or timeout: Stopping the client does not prove server-side work stopped. Assess duplicate-work risk before submitting another Responses request because the endpoint has no documented idempotency key.
  • Native SVG streams emit preview events before the final content event. Do not persist a preview.
  • data: [DONE] ends the transport. Evaluate the terminal event that preceded it to determine the request outcome.

Test error handling

Test keys use the production base URL and published response shapes without model calls or charges. Use the sandbox’s deterministic outcomes and supported failure markers to exercise client handling. The sandbox does not implement /v1/responses; see Sandbox and test keys.

Escalate a persistent failure

Provide support with:

  • the X-Request-ID or error request_id;
  • UTC timestamp, endpoint, model, HTTP status, and machine-readable code;
  • a minimal reproduction and sanitized request shape;
  • whether the request was streaming and which terminal event arrived.

Never send an API key or other secret. Include prompts, source assets, or generated output only when they are necessary to reproduce the issue and your data-sharing policy permits it.

Was this page helpful?