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

# Limits & Errors

> Daily caps, the OpenAI-style error envelope, and every status code your integration should handle.

## Daily limits

Every metered key has two independent daily caps, reset at **midnight UTC**:

| Limit            | Default | Behavior when hit                        |
| ---------------- | ------- | ---------------------------------------- |
| Requests per day | 10,000  | `429` with `code: "daily_request_limit"` |
| Spend per day    | \$50.00 | `429` with `code: "daily_spend_limit"`   |

Both are checked **before** the request runs, so a blocked request is never billed. Caps are configured per key — [ask us](/gateway/get-access) if your workload needs more. Partner (unmetered) keys have no daily caps.

Request size limits: at most **1,000 messages** per request, and `max_tokens` may not exceed the model's context length.

## Error envelope

Errors follow the OpenAI format, so existing SDK error handling works:

```json theme={null}
{
  "error": {
    "message": "Daily spend limit reached for this key",
    "type": "rate_limit_error",
    "code": "daily_spend_limit"
  },
  "limit": { "type": "spend", "cap": 50000000 }
}
```

The extra `limit` object appears only on `429` responses — `cap` is the configured cap (requests, or spend in micro-USD).

## Status codes

| Status | Type                                       | When                                                                                       |
| ------ | ------------------------------------------ | ------------------------------------------------------------------------------------------ |
| `400`  | `invalid_request_error`                    | Malformed JSON, unknown model, invalid parameters                                          |
| `401`  | `authentication_error` / `invalid_api_key` | Missing, invalid, or revoked key                                                           |
| `402`  | payment required                           | No key and no valid x402 payment — response carries the payment challenge                  |
| `429`  | `rate_limit_error`                         | Daily request or spend cap reached (see above)                                             |
| `5xx`  | `server_error` / upstream                  | Upstream model failure or gateway error — any reserved hold is released, nothing is billed |

## Handling failures

* **Retries:** `5xx` responses are safe to retry — failed calls are never charged. Use exponential backoff; don't retry `400`/`401`.
* **`429`:** back off until midnight UTC or switch to a cheaper model; the `limit` object tells you which cap you hit.
* **Support:** every response includes an `X-Request-Id` header. Include it in any report — we can trace the exact request.

## Insufficient credits

When a metered key's prepaid balance can't cover a request's reserve, the request is rejected before running. Top-up terms are part of your access agreement — contact us to add credits or review your invoice schedule.