Errors

Last updated October 8, 2026

Errors come back in the format of the API you called: OpenAI's error object from /v1/chat/completions, /v1/responses, /v1/embeddings, and /v1/models, and Anthropic's from /v1/messages. Error-handling code written for either SDK keeps working unmodified.

Error shape

OpenAI format, used by every endpoint except /v1/messages:

{
  "error": {
    "message": "This virtual key is not permitted to use model 'openai/gpt-4o'.",
    "type": "invalid_request_error",
    "code": "model_not_allowed"
  }
}

Anthropic format, used by /v1/messages. It has no code: error.type follows the HTTP status, as it does on Anthropic's own API, and the message is the same one the OpenAI format carries.

{
  "type": "error",
  "error": {
    "type": "permission_error",
    "message": "This virtual key is not permitted to use model 'openai/gpt-4o'."
  }
}

Every response, errors included, carries an x-tempr-request-id header. It matches the request in your request logs; include it when contacting support about a specific request.

Error codes

Every error the gateway itself returns, by what it concerns. An error from the provider behind a request is covered under provider errors.

Authentication

The request

Embeddings

From /v1/embeddings, all before any quota is spent.

Prompt templates

Models & providers

Limits & billing

Fallback chains & backup keys

Remote MCP proxy

Some refusals come back as JSON-RPC errors inside a 200, so MCP clients show them as tool errors:

• -32602: a tool call's arguments were blocked by the MCP guardrails. The message names what was found, for example "an AWS access key". The request log records mcp_guardrail_blocked.
• -32042 (MCP's URLElicitationRequiredError): the member needs to sign in first. data.elicitations[0].url is the Portal sign-in link. The log records mcp_sign_in_required.
• -32001: the server refused the call because the member's sign-in lacks a permission (insufficient_scope). The message names it. The log records mcp_insufficient_scope.

A withheld tool result is a normal result with isError: true and the reason as its text; the log records mcp_guardrail_withheld.

See remote MCP proxy for what comes back from the server itself.

Members' own requests

An organization's members reach models through Tempr's IDE extensions, the CLI and agent runs, not with a virtual key. Their requests answer these errors, as { "error": "…", "message": "…" }, plus currentSpendUsd and limitUsd for a budget. See Group budgets and models.

Every budget applies, and the first one used up refuses the request. In an agent run on Tempr's servers, the run ends with the same message.

Limit headers

A request refused by a limit carries headers saying which limit and where you stand:

Strict budgets

A budget checks what's already been spent, so requests that run at the same time can each pass the check and together spend past it. A key's budget, or an organization's hard cap, can be made strict: in the Portal, or with hold_worst_case in the management API. A strict budget sets aside each request's worst case while it runs, and refuses a request whose worst case doesn't fit in what's left:

{"error":{"message":"This request could cost up to $0.0750 and this virtual key's monthly budget has $0.0010 left. Lower max_tokens, or raise the budget.","type":"billing_error","code":"virtual_key_budget_exceeded"}}

• The worst case is the request's input at its model's price, plus max_tokens of output. Without max_tokens, Tempr assumes at most 8,192 output tokens, so set it when you need the true worst case held. A model with no known price sets nothing aside.
• A strict budget adds about 5 milliseconds to each request, up to about 30 when many requests share it at once. Near the limit, requests that start together can all be refused when one of them would have fit; retrying gets through.
• What's set aside is released as soon as the request ends; only what it actually cost counts toward the budget.

Retries & fallback

Tempr already retries transient upstream 429/5xx errors against the same provider before giving up, and — if you've configured a fallback chain on the key — falls back to the next candidate model automatically. When a provider asks for a wait longer than ten seconds, Tempr doesn't sleep through it: the 429 or 503 comes back at once with a Retry-After header carrying the provider's wait. A rate-limited model also sits out fallback chains until then, while that provider's other models stay available. A client-visible error means Tempr's own retry and fallback logic was exhausted, so honor Retry-After when it's there rather than retrying in a tight loop.

Provider errors

When the provider behind a request rejects it and Tempr's retries and fallbacks don't recover, you get the provider's HTTP status and its error message rather than one of the codes above. Tempr tidies a JSON error body into an error object with a message; a provider error that isn't JSON comes back as the provider sent it.

Errors during a stream

Once a streaming response has started, its status is already 200, so a failure after that point arrives in the stream. On /v1/chat/completions, a stream the provider cuts off before it finishes ends with this chunk, then data: [DONE]:

data: {"choices":[{"delta":{},"finish_reason":"error","index":0}],"error":{"message":"upstream stream closed prematurely","type":"stream_truncated"}}

Treat a finish_reason of "error" as a failed request: the output before it is incomplete.