> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ninjachat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Fallbacks

> Provide ordered model candidates and let NinjaChat fail over across models and provider rails.

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.

```mermaid theme={null}
flowchart LR
    A["claude-sonnet-5"] -->|"rail unavailable"| B["gpt-5.6-terra"]
    B -->|"success"| R["Response"]
    B -.->|"if unavailable"| C["gemini-3.1-pro"]
```

<CodeGroup>
  ```typescript TypeScript SDK theme={null}
  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);
  ```

  ```python Python SDK theme={null}
  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"])
  ```

  ```bash cURL theme={null}
  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}
    }'
  ```
</CodeGroup>

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.

<Tip>
  Fallbacks protect reliability. Use [Smart routing](/smart-routing) when you also want the router to choose the model class.
</Tip>