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

# Errors, rate limits, and retries

> Handle failures without dropping data or creating retry storms.

Hobbes returns JSON errors with a `detail` field and attaches `X-Request-ID`
to successful and failed requests. Authentication, authorization, missing
resource, rate-limit, and server errors use a string:

```json theme={null}
{
  "detail": "Insufficient scope"
}
```

Validation errors use an array so each invalid path or query parameter can be
identified separately:

```json theme={null}
{
  "detail": [
    {
      "type": "less_than_equal",
      "loc": ["query", "limit"],
      "msg": "Input should be less than or equal to 200",
      "input": "201"
    }
  ]
}
```

## Status codes

| Status | Meaning                                                                        | Retry?                              |
| ------ | ------------------------------------------------------------------------------ | ----------------------------------- |
| `200`  | Request succeeded                                                              | No                                  |
| `202`  | Asynchronous job accepted                                                      | Poll the job URL                    |
| `304`  | Polled job is unchanged                                                        | Continue after the polling interval |
| `401`  | Key missing or invalid                                                         | No, replace or fix the key          |
| `403`  | Required scope missing                                                         | No, create a correctly scoped key   |
| `404`  | Resource unavailable to this organization                                      | No                                  |
| `409`  | Idempotency key conflict or delivery URL unavailable                           | No, correct the request             |
| `422`  | Path or query parameter failed validation                                      | No, fix the request                 |
| `429`  | Request, transcript, Custom Link, render, or organization queue quota exceeded | Yes, after `Retry-After`            |
| `503`  | Global queue or worker circuit breaker unavailable                             | Yes, after `Retry-After`            |
| `5xx`  | Temporary server failure                                                       | Yes, with exponential backoff       |

## Rate limits

Keys allow 120 requests per 60-second window by default. Hobbes may configure a
different limit for a specific key.

Custom Link creation, thumbnail, and retry operations also allow 10 requests per
minute per organization. Job polling allows 300 per minute per organization
while retaining the lower 120-per-key limit. Creation and thumbnail compute have
separate weighted hourly and daily quotas; see [Create Custom Links](/guides/custom-links).

```text theme={null}
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
```

On `429`, sleep for the number of seconds in `Retry-After`. Add jitter if many
workers share the same key.

```python theme={null}
import random
import time

if response.status_code == 429:
    retry_after = int(response.headers.get("Retry-After", "30"))
    time.sleep(retry_after + random.random())
```

For `5xx` and network failures, retry a bounded number of times with exponential
backoff. Do not retry authentication, authorization, validation, or missing
resource errors.

## Support diagnostics

Log these values for every failed request:

* HTTP method and path, excluding secret query data
* Response status and `detail`
* `X-Request-ID`
* Attempt number and next retry time

Never log the `Authorization` or `x-api-key` header.