Debug Mode

Opt in with extra.debug and OpenGateway returns a top-level debug object — normalizations, deprecations, and routing — so you see exactly what the gateway did.

A gateway sits between you and the provider. Debug mode makes that layer transparent: ask for it, and the response tells you exactly what OpenGateway did to your request.

How to use it#

Add extra.debug with the categories you want. The response carries a top-level debug object containing only those categories.

{
  "model": "openai/gpt-4o-mini",
  "messages": [{ "role": "user", "content": "Hello" }],
  "extra": { "debug": ["normalizations", "deprecations", "routing"] }
}

category	what it shows
`normalizations`	parameters the gateway corrected or transformed — see Parameter normalization
`deprecations`	deprecated fields you sent, with what to use instead
`routing`	which provider/region the gateway tried, in order

"debug": {
  "normalizations": [ ... ],
  "deprecations": [
    { "param": "max_tokens", "message": "Use max_completion_tokens instead." }
  ],
  "routing": [
    { "provider": "openai", "region": "global", "status": "succeeded" }
  ]
}

Debug is opt-in. When you do not ask for it, there is no debug object and no extra cost.

What normalizations excludes#

normalizations shows only the fields OpenGateway actually rewrote. Some fields are intentionally left out of the diff to avoid false positives:

group	excluded fields
Prompt / Message body	`messages`, `contents`, `instructions`, `system_instruction`, `prompt`, `input`
OG extensions	`extra`, `native_fields`
Transport	`stream`

Prompt and message fields differ structurally between providers (e.g. OpenAI uses messages, Gemini uses contents). Including them in the diff would always produce noise, not signal.

OG extension fields (extra, native_fields) are OpenGateway-specific and never forwarded verbatim to the provider, so they have no meaningful before/after to compare.

stream is a transport control flag that the gateway handles internally.