Fallbacks

Pass an ordered models array and enable fallbacks. NinjaChat first tries the strongest eligible rail for the first model, then advances safely when a provider or model cannot serve the request.

const response = await client.responses.create({
  models: ["claude-sonnet-5", "gpt-5.6-terra", "gemini-3.1-pro"],
  input: "Review this contract clause for hidden risk.",
  routing: {
    strategy: "quality",
    allow_fallbacks: true,
    require_parameters: true,
  },
});

console.log(response.routing.requested_models);
console.log(response.routing.resolved_model, response.provider);

response = client.responses.create(
    models=["claude-sonnet-5", "gpt-5.6-terra", "gemini-3.1-pro"],
    input="Review this contract clause for hidden risk.",
    routing={
        "strategy": "quality",
        "allow_fallbacks": True,
        "require_parameters": True,
    },
)

print(response["routing"]["resolved_model"], response["provider"])

curl https://www.ninjachat.ai/api/v1/responses \
  -H "Authorization: Bearer $NINJACHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "models":["claude-sonnet-5","gpt-5.6-terra","gemini-3.1-pro"],
    "input":"Review this contract clause for hidden risk.",
    "routing":{"strategy":"quality","allow_fallbacks":true,"require_parameters":true}
  }'

You are billed only for the successful execution. Failed infrastructure attempts do not become customer usage.

Parameters

Parameter	Default	Description
`models`	—	1–15 ordered candidate model IDs. Use instead of `model`. `ninja/auto` may appear only as the first entry — anywhere else is `400 invalid_model`.
`routing.allow_fallbacks`	`true`	Permit the router to advance across eligible rails and models. A project routing policy can change the default for keys in that project.
`routing.require_parameters`	`true`	Skip rails that cannot honor every requested parameter or capability. Set `false` to let a rail serve on a best-effort basis.
`routing.providers`	—	Constrain or order the infrastructure providers behind the model IDs (`only`, `exclude`, `order`; up to 20 each — `only` and `exclude` can’t be combined).

If every candidate fails before producing output you get 502 all_providers_failed and are not charged; if no candidate is currently servable under your routing policy you get 503 no_eligible_model. With stream: true the connection is already open (the gateway commits the 200 and starts sending : keepalive comments as soon as your request is admitted), so the same failure arrives as an in-band error frame — data: {"error": {"code": "all_providers_failed", ...}} followed by data: [DONE] — exactly as a mid-stream failure would. Billing: metered usage comes from the successful resolved model and provider shown in the response.

Fallbacks protect reliability. Use Smart routing when you also want the router to choose the model class.

Get started

Controls

Parameters

​Parameters

Parameters