Proxy errors

Proxy-generated errors use this shape:

{
  "error": {
    "message": "No routing configuration for project 'your-team/ticket-classifier'",
    "type": "proxy_error"
  }
}

Every response includes x-proxy-request-id. Include it when reporting a problem.

Common failures

Status	Typical cause	Action
`400`	Invalid metadata or malformed JSON	Correct the request body
`400`	`OpenAI-Project must be entity/project`: the header isn’t `[ENTITY]/[PROJECT]`. For an OpenAI project ID such as `proj_abc123`, often left over in `OPENAI_PROJECT_ID`, the error includes a hint to unset or change the variable	Set the SDK’s `project` option or `OPENAI_PROJECT_ID` to `[ENTITY]/[PROJECT]`
`400`	A project alias or `alias@vN` in `model` together with `OpenAI-Project`	Send `model: "router"` and select the version with `metadata["forge.project_version"]`
`400`	`forge.project_version` sent without `OpenAI-Project`, or a value that isn’t a positive integer	Send the header, and a version such as `"2"`
`400`	An invalid `Forge-Cache-Mode` value or a cache request for a streaming call	Correct or remove the cache header
`401`	Missing or invalid Forge API key	Use a current API key
`403`	The key can’t access the entity in `OpenAI-Project`. The proxy checks access before any project lookup	Change the entity or grant team access
`404`	`No routing configuration for project '[ENTITY]/[PROJECT]'`: wrong project name, often the project alias where the Weights & Biases project name differs, or routing isn’t published yet	Copy the `OpenAI-Project` value from Studio, and wait until routing is applied
`404`	`Project '[ENTITY]/[PROJECT]' has no version N`: `forge.project_version` names a version that doesn’t exist	Create the version or correct the value
`404`	`model: "router"` sent without `OpenAI-Project`. The message says to send the header	Set the SDK’s `project` option or `OPENAI_PROJECT_ID`
`404`	Unknown provider in a model override, or an unsupported path	Check the provider name and provider deployment
`502`	Provider could not be reached or its response stream failed	Inspect provider availability and credentials
Provider status	The selected provider returned an error	Read the provider response. The proxy preserves upstream status and body

The most common project mistake

OpenAI-Project takes the project’s Weights & Biases project name, not its project alias. The two differ when the project was created with a project name other than the alias. In that case, the alias in OpenAI-Project returns 404 with No routing configuration for project. Copy the value from the project header in Studio:

OpenAI-Project: your-team/ticket-classifier

A model ID error is not a proxy `404`

The proxy validates the provider name, not every upstream model ID. If the provider exists but the model does not, the selected provider returns its own error. This distinction helps separate routing configuration from provider catalog drift.

Tracing failures

Trace writes are asynchronous and do not turn a successful provider response into a client failure. Operators monitor structured write-failure events with the same proxy request ID. Deterministic trace-input problems are rejected before provider dispatch when possible.

API: Diagnose a failure

Provide the agent with the request URL, the OpenAI-Project header value, a redacted request body, the HTTP status, the full response body, and x-proxy-request-id. Do not share the bearer key or provider credential.An agent should check the following in order:

The OpenAI-Project value, and whether its project is the Weights & Biases project name rather than the project alias.
Whether model is router or a model override, and which version forge.project_version selects.
Whether the provider and routing deployment are applied.
Whether the response body came from the proxy or the upstream provider.

For error response schemas, see the Chat Completions API reference.

Model Distillation

Serverless Training

Common failures

The most common project mistake

A model ID error is not a proxy `404`

Tracing failures

Common failures

The most common project mistake

A model ID error is not a proxy 404

Tracing failures

A model ID error is not a proxy `404`