Core Concepts
Error Handling
Errors are JSON, they carry a status code, and they tell you whether to retry.
OpenLink returns errors as HTTP status codes with a single JSON envelope — the same envelope whether the failure came from your request or from a provider. The type and code fields tell you what happened; retryable tells you what to do next.
The error envelope
{
"error": {
"type": "provider_error",
"code": "provider_rate_limited",
"message": "Anthropic returned HTTP 429 after 2 retries.",
"provider": "anthropic",
"retryable": true,
"request_id": "req_01J8R2aKq..."
}
}| Field | Meaning |
|---|---|
| type | Broad class: invalid_request, auth, rate_limit, provider. |
| code | Stable, machine-readable code. Safe to match on. |
| message | Human-readable detail. |
| provider | Which provider was at fault, when applicable. |
| retryable | Whether retrying the same request may succeed. |
| request_id | Correlates with the request in your dashboard. |
HTTP status codes
| Status | When |
|---|---|
| 400 | Malformed body or unsupported field. |
| 401 | Missing or invalid API key. |
| 402 | Key has no spending attached (beta: ad-hoc). |
| 404 | Unknown endpoint or model. |
| 422 | The request failed validation. |
| 429 | Rate limit hit. Honor Retry-After. |
| 500 | Internal gateway error. |
| 502 | Upstream provider error, retries exhausted. |
| 503 | No healthy provider can serve the request. |
| 529 | Provider is overloaded. Retryable. |
Retryable errors
429, 502, and 529 responses set retryable: true. The gateway already retries internally before surfacing a provider error to you — when an error reaches your code, you are usually looking at the exhausted case.
Retry consistently
Match on error.code, not status text, so your handling stays stable as types evolve. The Retries guide covers the practical pattern.
SDK exceptions
try {
await client.chat({ messages });
} catch (err) {
if (err.status === 429) {
const wait = Number(err.headers.get("retry-after")) * 1000;
await sleep(wait);
return retry();
}
if (err.retryable) return retry();
throw err;
}