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

# Errors

> Error response format and common error codes.

urltodata uses standard HTTP status codes and returns errors in a consistent JSON format.

## Error format

```json theme={null}
{
  "error": "Short error type",
  "message": "Human-readable description of what went wrong"
}
```

## HTTP status codes

| Code  | Meaning                                                   |
| ----- | --------------------------------------------------------- |
| `200` | Success                                                   |
| `202` | Accepted — async job created, poll for results            |
| `400` | Bad request — missing or invalid parameters               |
| `401` | Unauthorized — missing or invalid Bearer token            |
| `402` | Payment required — insufficient credits                   |
| `404` | Not found — resource doesn't exist                        |
| `409` | Conflict — resource already exists (e.g. duplicate email) |
| `429` | Rate limited — too many requests                          |
| `500` | Internal server error                                     |

## Common errors

### Missing API key

```bash theme={null}
curl "https://api.urltodata.ai/v1/youtube/video?id=dQw4w9WgXcQ"
```

```json 401 theme={null}
{
  "error": "unauthorized",
  "message": "Missing or invalid API key"
}
```

### Missing required parameter

```bash theme={null}
curl -H "Authorization: Bearer your-api-key" \
  "https://api.urltodata.ai/v1/youtube/video"
```

```json 400 theme={null}
{
  "error": "invalid_request",
  "message": "Missing required parameter: id"
}
```

### Insufficient credits

```json 402 theme={null}
{
  "error": "insufficient_credits",
  "message": "Not enough credits. Purchase more at /v1/credits/packages"
}
```

### Resource not found

```json 404 theme={null}
{
  "error": "not_found",
  "message": "Video not found or unavailable"
}
```

### Rate limited

```json 429 theme={null}
{
  "error": "rate_limited",
  "message": "Too many requests. Try again later."
}
```

## Rate limiting

Requests are rate limited per API key. If you receive a `429` response, back off and retry. Use exponential backoff starting at 1 second.