Errors

Tokentide’s own errors use the OpenAI-compatible envelope, so the OpenAI SDKs (and anything built on them) raise them as normal API errors with a code:

{
  "error": {
    "message": "Low Tide is closed right now. It is forecast to open at 19:40 UTC.",
    "type": "tokentide_error",
    "code": "lowtide_closed",
    "param": null,
    "request_id": "req_01JDV6Q7Z8R2M3N4P5Q6R7S8T9"
  }
}

• type is always tokentide_error for errors Tokentide generates. Upstream errors that Tokentide passes through keep Venice’s body (see Upstream errors).
• code is stable; match on it, not on message.
• param names the offending field or header when there is one.
• request_id equals the X-Request-Id header. Quote it to support.
• Retry-After (seconds) is set whenever waiting will help.

Error codes#

Every code, its HTTP status and what to do. Link to a row with its code, for example /docs/errors#lowtide_closed.

Upstream errors#

Validation errors from Venice are passed through with their status and body, because clients expect Venice semantics there: 400, 404, 413, 415 and 422 (including the OpenAI-style context_length_exceeded). Their body is Venice’s ({"error": "…"}, sometimes with details and issues, or {"error": {…}} for context-length errors), not the Tokentide envelope.

Some upstream errors are never passed through, because they concern our supply, not your request:

Images flagged by Venice as content violations come back as 200 with x-venice-is-content-violation: true and are not charged. 422 content-policy rejections are normally not charged either.

Errors inside a stream#

Once a stream has started, the HTTP status is already 200. If the upstream fails after that, the error arrives in-band, passed through untouched, followed by the terminator:

data: {"error":{"message":"…","type":"server_error","code":"model_overloaded","param":null,"retry_after":30}}
 
data: [DONE]

Treat an in-band error as terminal. Tokentide never retries a request whose stream has started. If a stream ends without its final usage chunk (an in-band error, a dropped connection or your own disconnect), the request is settled provisionally at its worst-case cost, never more than was reserved for it, and trued up against Venice’s own ledger for that request: anything Venice did not bill is credited back automatically.

The same applies to a non-streaming response that Venice answered but that could not be delivered to you (the connection was cut, the request ran out of time, or the body is larger than the 64 MB Tokentide relays without streaming). Venice has already billed it, so it is settled provisionally at its worst-case cost, never more than was reserved, and trued up against Venice’s ledger when the response carries Venice’s request id (chat completions and responses). Such a request keeps its Idempotency-Key: a retry with the same key answers 409 duplicate_request. Embeddings batches whose vectors would exceed 64 MB are refused up front with 400 invalid_request (param: "encoding_format"): send "encoding_format": "base64", a lower dimensions (on models that support it) or a smaller batch.

Retry rules#

• Never retry unchanged: 400, 401, 403, 404, 405, 413, 415, 422. Repeating them cannot succeed, and repeated client errors on one model trip a protective breaker: more than 10 upstream 4xx in 30 seconds from one customer answers 429 rate_limited for 30 seconds (this protects the shared upstream error budget).
• Retry after Retry-After: 409 price_above_limit, lowtide_closed, lowtide_cap_reached, 429, 503.
• Retry with exponential backoff and jitter (0.5 s, 1 s, 2 s, 4 s … capped at 30 s, 3–5 attempts): 500, 502.
• 402 is about money, not load: insufficient_balance clears only when your balance grows (top up, or turn on auto top-up); spend_limit_reached clears when the cap resets (Retry-After) or when you raise it; when only that request was too large for what is left, smaller requests still pass and Retry-After is 60 seconds. See Handling 402 errors.
• Use Idempotency-Key on retries of requests that may have been processed. A duplicate answers 409 duplicate_request instead of running twice.

Debugging a request#

Every response, successful or not, identifies the request:

• X-Request-Id (also request_id in the error envelope) is our id for the request. Quote it to support. Once the request has settled, the dashboard’s Request Inspector shows its metadata.
• X-Client-Request-Id is yours: send a correlation id (1–128 characters of letters, digits and . _ : / + = -, for example a UUID) and it is echoed back. We record only a keyed hash of it, never the id itself, so it can hold your own ids safely. It matters when a call timed out or failed before any response arrived, so you never saw an X-Request-Id: support can still find the request by your id. Other values are ignored, never rejected. The Tokentide SDKs send a random one with every request and print it in their errors.
• Public answers our CDN caches (GET /v1/market, /v1/status, /v1/openapi.json, /v1/image/styles, and /v1/models with its /traits and /compatibility_mapping without credentials) never echo X-Client-Request-Id: a cached answer is served to every caller. Their X-Request-Id can be the one of the request that filled the cache.

Add X-Tokentide-Debug: 1 to see where the time went and what the upstream answered. Nothing extra is stored. Error responses carry these headers too, for the stages the request reached before it failed:

When you contact support, include the X-Request-Id (or your X-Client-Request-Id), the time in UTC, the host you called and the error code. Never send prompts or outputs: metadata is all we need, and all we keep.

Reading errors with the OpenAI SDKs#

import openai
 
try:
    client.chat.completions.create(
        model="deepseek-v4-1-flash",
        messages=[{"role": "user", "content": "…"}],
        extra_headers={"X-Tokentide-Lane": "lowtide"},
    )
except openai.APIStatusError as e:
    print(e.status_code, e.code, e.response.headers.get("retry-after"))
    print(e.response.headers.get("x-tokentide-lowtide-opens-at"), e.request_id)

The Tokentide SDKs raise a typed error with the code, Retry-After and the parsed X-Tokentide-* headers. See SDK helpers.