> ## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.