Tarseek API · Pre-production

Errors

Every public chat error uses one stable envelope:

{
  "error": {
    "message": "Human-readable explanation",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null,
    "retryable": false
  },
  "request_id": "req_..."
}

Implemented

x-request-id always matches the body request_id. Send an optional printable-ASCII X-Client-Request-Id (maximum 512 characters) to correlate the call with your own logs; Tarseek echoes it in the response. Retryable provider throttling includes Retry-After and error.retry_after_seconds when the provider supplied a delay. The body field remains available for errors emitted after an SSE stream has started.

HTTP	Code	Type	Retry	Cause	Action	Backend
400	`invalid_request`	`invalid_request_error`	No	Semantically invalid body	Fix the request	Implemented as validation_error for schema validation
400	`malformed_json`	`invalid_request_error`	No	Body is not JSON	Send application/json	Normalized to validation_error
401	`authentication_required`	`authentication_error`	No	Missing Authorization	Add Bearer token	Intentionally normalized to invalid_api_key
401	`invalid_api_key`	`authentication_error`	No	Unknown key	Create a new key	Implemented
401	`api_key_revoked`	`authentication_error`	No	Key disabled	Use an active key	Not implemented
503	`provider_billing_error`	`provider_error`	No	The BYOK provider account cannot accept billed requests	Check billing with the model provider	Implemented
404	`model_not_found`	`invalid_request_error`	No	Unknown or unlisted model ID	Use the catalog	Implemented — unknown and unlisted IDs are indistinguishable
400	`unsupported_parameter`	`invalid_request_error`	No	Param not on this model	Remove the field	Implemented — rejected before provider execution
400	`unsupported_modality`	`invalid_request_error`	No	Image/audio sent to text-only model	Pick a multimodal model	Partial — unsupported primary deployments may return 503
400	`context_length_exceeded`	`invalid_request_error`	No	Prompt longer than context	Shorten input	Implemented
429	`rate_limit_exceeded`	`provider_error`	Yes	Account RPM/TPM	Backoff using Retry-After	Implemented — project and optional key limits return Retry-After and remaining-limit headers
429	`provider_rate_limit`	`rate_limit_error`	Yes	Primary deployment returned 429	Retry later or another model	Implemented — Retry-After is forwarded when available
503	`model_unavailable`	`service_unavailable_error`	Yes	No healthy deployment	Retry or switch model	Implemented
503	`deployment_unavailable`	`provider_error`	Yes	Requested provider down	Retry or switch model	Not implemented — not distinct
502	`provider_error`	`api_error`	Yes	Upstream 5xx	Retry with backoff	Implemented as the sanitized terminal provider failure
502	`provider_authentication_error`	`provider_error`	Yes	Tarseek credential for provider is bad	Report to support; try another model	Implemented — distinct from customer authentication
504	`provider_timeout`	`timeout_error`	Yes	Upstream deadline	Retry; reduce max output	Implemented
400	`content_filter`	`safety_error`	No	Prompt or output blocked	Revise content	Not implemented — not a Tarseek code
500	`internal_error`	`internal_error`	Yes	Tarseek bug	Retry; contact support with request_id	Implemented for public /v1 failures