# Actionable model availability errors with structured error.availability object

> OpenRouter now returns a structured `error.availability` object on API error envelopes when a model cannot be used, replacing free-text prose with 11 stable machine-readable codes across all three API skins. The change is additive but includes one behavioral shift: unknown model IDs on the Chat Completions router now consistently return HTTP 400 instead of the previous 500.

| | |
|---|---|
| **Tool** | openrouter |
| **Version** | — |
| **Kind** | announcement |
| **Published** | 2026-08-19 |
| **Observed** | 2026-08-21 |
| **Significance** | 3/5 |
| **Breaking** | yes |
| **Categories** | feature, api-change, breaking, docs |

## What changed


- New `error.availability` object on error envelopes for non-streaming responses and streaming error chunks across Chat Completions, Responses, and Anthropic Messages skins
- 11 stable error codes: `model_not_found`, `wrong_endpoint`, `no_endpoints`, `model_deprecated`, `model_unavailable_upstream`, `capacity_exhausted`, `temporarily_unavailable`, `region_restricted`, `privacy_restricted`, `constraint_filtered`, `free_variant_ended`
- Fields include: `retryable`, `retry_after`, `requested_models`, `affected_providers`, `excluded_by`, `fallback_models`, `constraint`, `docs_url`
- Additive and backward compatible — `error_type`, `http_status`, and `message` unchanged
- **Breaking**: unknown model IDs on Chat Completions now return HTTP 400 consistently (previously could surface as 500)
- `retry_after` mirrors the `Retry-After` header in the response body
- `error.metadata.previous_errors` slimmed to `{provider, code, status}` — no longer carries raw upstream provider error bodies


## Sources

- [blog_rss](https://openrouter.ai/docs/changelog#august-19-2026) — retrieved 2026-08-21


## Community

_No curated reactions recorded. Facts and community takes are kept in separate layers
and never blended._

---
Canonical: https://changelogs.info/openrouter/actionable-model-availability-errors-with-structured-error-availability-object
Entity: https://changelogs.info/openrouter
Event ID: `evt_2026-08-19_openrouter_august-19-2026`
Licence: event synthesis © changelogs.info, CC BY 4.0. Linked sources belong to their vendors.