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

# Errors and Rate Limits

> Common OmniaKey API error responses, quota errors, and rate-limit troubleshooting.

OmniaKey returns protocol-compatible errors where possible, so your existing SDK
error handling continues to work.

## Common status codes

| Status | Meaning                                                                              |
| ------ | ------------------------------------------------------------------------------------ |
| `400`  | Invalid request body, unsupported field, or malformed parameter                      |
| `401`  | Missing or invalid API key                                                           |
| `403`  | Account balance, API key cap, model access, or policy restriction blocks the request |
| `404`  | Wrong path, wrong base URL suffix, or unknown model id                               |
| `429`  | OmniaKey or upstream provider throttling                                             |
| `500`  | OmniaKey or upstream provider error                                                  |

## Base URL mistakes

Most setup errors come from using the wrong protocol suffix:

| Tool or SDK             | Correct base URL                  |
| ----------------------- | --------------------------------- |
| OpenAI-compatible       | `https://api.omniakey.com/v1`     |
| Anthropic / Claude Code | `https://api.omniakey.com`        |
| Gemini native           | `https://api.omniakey.com/v1beta` |

If Claude Code calls a path like `/v1/messages`, the base URL should be the bare
host. If an OpenAI SDK gets a 404, confirm it includes `/v1`.

## Quota errors

A `403` can mean either:

* the account balance is too low, or
* the API key's per-key cap has been reached.

Check both the account balance and the key cap in the
[Dashboard](https://omniakey.com/dashboard/tokens).

## Rate limits

OmniaKey supports route-level and model-request throttling, and upstream
providers can also return `429` through the relay. Public docs do not publish
fixed thresholds because limits can vary by route, account/group configuration,
and provider.

Treat `429` as a retryable throttling signal: retry with exponential backoff,
add jitter, and avoid sending the same burst again immediately.

## Unsupported endpoints

If an endpoint is not documented in the API Reference, treat it as unsupported
for public use. The most common examples are image generation, audio, embeddings,
rerank, files, fine-tuning, and batches.