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

# Errors and rate limits

> Common Fetch Hive API error responses, status codes, and workflow concurrency behavior

Fetch Hive returns JSON errors for invalid or failed public API requests. Runtime public API errors include a human-readable `message`, a stable code, and `error` as a compatibility alias.

## Error response format

```json theme={null}
{
  "error": "Invalid access.",
  "message": "Invalid access.",
  "error_code": "validation_error"
}
```

Some plan and rate-limit responses also include `code` for compatibility with existing clients. New clients should read `error_code`. See [Error Codes](./error-codes) for the complete code list, catalog endpoint, and client handling guidance.

## Common status codes

### `401 Unauthorized`

Fetch Hive returns `401` when the `Authorization` header is missing, invalid, or uses a revoked API key.

Example:

```json theme={null}
{
  "error": "Invalid access."
}
```

### `404 Not Found`

Fetch Hive returns `404` when the resource does not exist for your account.

Example workflow run response:

```json theme={null}
{
  "error": "Prompt workflow run not found"
}
```

Example request lookup response:

```json theme={null}
{
  "error": "Request not found"
}
```

### `422 Unprocessable Entity`

Fetch Hive returns `422` when the request is authenticated but invalid for that endpoint.

Examples:

```json theme={null}
{
  "error": "Agent not found."
}
```

```json theme={null}
{
  "error": "Data set not found."
}
```

```json theme={null}
{
  "error": "You've reached your credit cap."
}
```

### `502 Bad Gateway`

Fetch Hive returns `502` when a provider fails while processing a prompt or agent request.

Example:

```json theme={null}
{
  "error": "openai API error: provider rejected the request"
}
```

## Rate limits and concurrency

Fetch Hive tracks **two independent daily meters** (UTC midnight reset):

1. **Public API** — counts requests authenticated with an API key through public/stream endpoints (including the Rust public invoke auth hop to `validate_key`). Cap comes from `plan.rate_limit_per_day`. Dashboard and other `/v1/private/*` first-party routes authenticate the same way but **do not** count against this meter.
2. **Provider tools** — counts costly third-party workflow tool runs (Google/Bing/Exa search, website scrape, etc.) from the dashboard, schedules, and public workflow API. Cap comes from `plan.provider_tool_calls_per_day`. Growth, Pro, and Enterprise have no provider-tool cap (`nil`).

Workflow failures from provider-tool caps return a plain error string in the run payload (same style as credit-cap errors). The structured code `provider_tool_rate_limit_exceeded` is returned by the internal agent pre-flight endpoint.

### Public API daily cap

Public API requests count against your plan daily API call cap. If you exceed that cap, Fetch Hive returns `429 Too Many Requests` before running the request.

Example daily API cap response:

```json theme={null}
{
  "error": "Daily API rate limit reached",
  "code": "api_rate_limit_exceeded",
  "message": "You have reached your daily limit of 50 API calls. Resets at midnight UTC. Upgrade your plan for higher limits.",
  "limit": 50,
  "current": 50
}
```

### Provider tool daily cap

| Plan                      | Provider tool calls / day |
| ------------------------- | ------------------------- |
| Developer                 | 15                        |
| Lifetime                  | 50                        |
| Growth / Pro / Enterprise | Unlimited                 |

Example workflow failure message:

```json theme={null}
{
  "error": "You've reached your daily limit of 15 provider tool calls. Resets at midnight UTC."
}
```

### Workflow concurrency

Workflow concurrency depends on your plan.

| Plan       | Concurrency cap |
| ---------- | --------------- |
| Lite       | 1               |
| Starter    | 3               |
| Pro        | 5               |
| Entreprise | Custom          |

If you exceed your concurrency cap, Fetch Hive returns `429 Too Many Requests`.

Example:

```json theme={null}
{
  "error": "You've reached your concurrency limit. Try again later or use async mode."
}
```

If you see this response on a workflow request, retry later or switch to callback delivery so Fetch Hive can queue the run.

## Related

* See [Authentication](./authentication) for the required bearer header
* See [Error Codes](./error-codes) for stable `error_code` values and `GET /v1/error_codes`
* See [Invoke Workflow](./workflows/invoke) for callback-delivery workflow requests