Errors & troubleshooting

CrossModel returns errors in the format that matches the protocol you called. OpenAI-compatible endpoints return OpenAI-style error objects; the Anthropic Messages endpoint returns Anthropic-style error objects.

OpenAI-compatible error format

{
  "error": {
    "message": "Missing Bearer token in Authorization header.",
    "type": "authentication_error",
    "param": null,
    "code": "missing_api_key"
  }
}

Field	Notes
`message`	A human-readable description.
`type`	The broad error category.
`param`	The offending field, or `null` when there isn't a specific one.
`code`	A stable error code — prefer branching on this in code.

Anthropic-compatible error format

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Missing API key."
  }
}

The Anthropic format doesn't include a code field. Branch on the HTTP status code and error.type.

Common errors

HTTP status	OpenAI `type`	Common `code`	Notes
`400`	`invalid_request_error`	`invalid_json`, `invalid_messages`, `unsupported_parameter`, `unsupported_responses_feature`	Malformed body or parameters.
`401`	`authentication_error`	`missing_api_key`, `invalid_api_key`, `api_key_inactive`, `user_inactive`	Key missing, wrong, disabled, or account unavailable.
`402`	`billing_error`	`insufficient_balance`, `no_wallet`	Out of balance or no wallet on the account.
`404`	`invalid_request_error`	`model_not_found`	Model doesn't exist, isn't listed, or is currently unavailable.
`429`	`rate_limit_error`	`rate_limit_exceeded`	Over the API key's RPM or TPM limit.
`502`	`provider_error`	`provider_error`	The model service couldn't complete the request.
`503`	`api_error`	`model_unavailable`	Model temporarily unavailable — retry shortly.
`500`	`api_error`	`internal_error`, `db_error`	Server error.

Request tracing

Successful responses include:

x-request-id: req_cm_...
x-crossmodel-model: vendor/model

When you report a problem, include as much of this as you can:

x-request-id
the request time
the model ID used
the HTTP status code
the error response body

Streaming errors

When an error happens after a streaming connection is already open, it comes back as an SSE event in the matching protocol:

Chat Completions sends a data: chunk with an error field.
Responses sends event: error.
Messages sends an Anthropic-style error event.

Once you receive a streaming error, treat that generation as failed. The client can let the user retry, or your business layer can start a fresh, complete request.

Debugging order

401: check the headers, that the key starts with cm-, and that the key is still usable.
402: check the console balance, top up, and retry.
404: call /v1/models to confirm the model ID.
429: lower concurrency or output cap, wait, and try again.
502 / 503: usually the model service is briefly unavailable — back off and retry.
Persistent failures: contact support with the x-request-id.