Errors

Every error response uses OpenAI’s envelope shape, regardless of which route or provider produced it.

{
  "error": {
    "message": "...",
    "type": "invalid_request_error",
    "code": "string | null",
    "param": "string | null"
  }
}

Same-provider upstream errors — an invalid OpenAI key on an OpenAI call, for example — are forwarded verbatim with the upstream’s original HTTP status. Gateway-originated errors (bad config, unknown model, unconfigured provider) use the same envelope shape with the gateway’s own code values.

Gateway error codes

Code	Cause
`config_invalid`	Config failed validation (missing provider, malformed entry)
`no_providers`	Zero providers configured — nothing to route to
`invalid_model_id`	Malformed model ID (missing or misplaced `/`)
`model_not_found`	Provider segment isn’t a known or configured name
`provider_not_configured`	Known provider name, but not present in the registry
`model_unsupported_operation`	Catalog says the model doesn’t support the requested operation
`unsupported_modality`	Provider has no model for the requested modality (e.g. no `videoModel`)
`invalid_request_body`	Request body failed shape validation
`request_entity_too_large`	Request exceeded `maxBodyBytes`
`invalid_tool_arguments`	Tool call arguments failed to parse
`resource_not_found`	Unknown route
`structured_output_invalid`	A strict JSON-schema reply still didn’t match the schema after one retry (502). See Strict structured output

Strict structured output

A request that asks for a strict JSON schema gets a reply that matches it, whichever provider serves the request. That means response_format.json_schema.strict: true on /v1/chat/completions, text.format.strict: true on /v1/responses, or any output_config.format on /v1/messages. Some providers can’t enforce a schema themselves. Amazon Bedrock rejects it for the newest Claude models, for example. So the gateway checks every such reply:

A reply that doesn’t match is sent back to the model once, with the problems listed, and the corrected reply is returned. Usage covers both calls.
If the second reply doesn’t match either, the request fails with 502 and structured_output_invalid.
A streamed reply has already been sent when the check runs, so it isn’t retried. The stream ends with an error event carrying structured_output_invalid.

Replies that call a tool or stop at the token limit aren’t checked. Requests without strict: true are passed through unchanged.

Build matching envelopes

Import error classes and envelope builders from the ./errors subpath for custom handlers or embedding hosts that need to produce gateway-compatible error responses.

import { GatewayError, toOpenAIErrorResponse, isGatewayError } from '@frogbotai/gateway/errors'

try {
  await handleRequest(req)
} catch (err) {
  if (isGatewayError(err)) {
    return toOpenAIErrorResponse(err)
  }
  throw err
}

toAnthropicErrorResponse produces the equivalent envelope for the /v1/messages route’s wire format. For an error that is not a GatewayError, toStatusErrorResponse builds the same envelope from a status, taking type and a default code from the status:

import { toStatusErrorResponse } from '@frogbotai/gateway/errors'

const { body, status } = toStatusErrorResponse('openai', { status: 401, message: 'Unauthorized' })
// 401 { error: { message: 'Unauthorized', type: 'authentication_error', code: 'invalid_api_key', param: null } }

Pass 'anthropic' for the /v1/messages shape, and code or param to set them.

Error classes

ConfigError, ModelIdError, ProviderNotConfiguredError, UnsupportedModalityError, RequestValidationError, BodyTooLargeError, InvalidToolArgumentsError, ModelNotFoundError, ModelUnsupportedOperationError, NotFoundError, NoProvidersError, and StructuredOutputError all extend GatewayError and carry a code matching the table above.

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Gateway error codes

Strict structured output

Build matching envelopes

Error classes

​Gateway error codes

​Strict structured output

​Build matching envelopes

​Error classes

Gateway error codes

Strict structured output

Build matching envelopes

Error classes