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

# Errors

> HTTP status codes, error response structure, and handling guidance for the Everflow API.

The Everflow API uses conventional HTTP status codes. Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate a client error. Codes in the `5xx` range indicate a server-side issue.

## Error response body

Error responses return a JSON object carrying a human-readable message:

```json theme={null}
{
  "error": "descriptive error message"
}
```

<Warning>
  **The field name is not consistent — read both spellings.** Errors raised by an endpoint
  itself (validation failures, "Can't find entry in the database") use the lowercase `error`
  shown above. Errors raised before the endpoint runs — `401`, `403`, `405`, and
  router-level `404` — instead use a capitalised **`Error`**, with the same kind of message.

  A client that reads only one spelling will report "Unknown error" for a large share of
  real failures, including every authentication and permission problem. Until this is
  unified, read `error` and fall back to `Error`.
</Warning>

## Status codes

| Code  | Meaning               | Common causes                                                                                                                                                     | Should retry?                                                                        |
| ----- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `200` | OK                    | The request succeeded.                                                                                                                                            | —                                                                                    |
| `400` | Bad Request           | Missing or malformed parameters, invalid JSON body, unsupported field values.                                                                                     | No — fix the request.                                                                |
| `401` | Unauthorized          | Missing `X-Eflow-API-Key` header (returned as `Unable to authenticate request`), or an invalid or revoked API key (returned as `No authentication method found`). | No — check your key.                                                                 |
| `403` | Forbidden             | Wrong API key type for the endpoint (returned as `Out of realm` — e.g. using an Affiliate key on a Network endpoint), or insufficient permissions on the key.     | No — use the correct key.                                                            |
| `404` | Not Found             | The resource ID does not exist, or the URL path is incorrect.                                                                                                     | No — verify the ID and endpoint path.                                                |
| `429` | Too Many Requests     | Rate limit exceeded. See [Rate Limiting](/user-guide/rate-limiting).                                                                                              | Yes — after a backoff.                                                               |
| `500` | Internal Server Error | An unexpected issue on the Everflow side.                                                                                                                         | Yes — with backoff. If persistent, contact [Support](https://helpdesk.everflow.io/). |
| `503` | Service Unavailable   | The server is temporarily unavailable — typically during a deployment or under extreme load.                                                                      | Yes — with backoff.                                                                  |
| `504` | Gateway Timeout       | The request timed out upstream. Usually transient.                                                                                                                | Yes — with backoff.                                                                  |

## Handling errors in code

Check the HTTP status code first, then read `error` (falling back to `Error`) for details.

```bash theme={null}
# Example: invalid request
curl -s -w "\nHTTP Status: %{http_code}\n" \
  -H "X-Eflow-API-Key: <your-api-key>" \
  https://api.eflow.team/v1/networks/reporting/entity/table

# Response:
# {"error": "Invalid parameters."}
# HTTP Status: 400
```

```python Python theme={null}
import requests

response = requests.get(
    "https://api.eflow.team/v1/networks/reporting/entity/table",
    headers={"X-Eflow-API-Key": "<your-api-key>"}
)

if response.ok:
    data = response.json()
else:
    body = response.json()
    error_message = body.get("error") or body.get("Error") or "Unknown error"
    print(f"Request failed ({response.status_code}): {error_message}")
```

```javascript Node.js theme={null}
const response = await fetch(
  "https://api.eflow.team/v1/networks/reporting/entity/table",
  { headers: { "X-Eflow-API-Key": "<your-api-key>" } }
);

if (!response.ok) {
  const body = await response.json();
  console.error(`Request failed (${response.status}): ${body.error ?? body.Error}`);
}
```

## Retry strategy

Only retry on `429` and `5xx` errors. Client errors (`400`, `401`, `403`, `404`) will not succeed on retry without changes to the request.

When retrying, use **exponential backoff with jitter** to avoid overwhelming the API:

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

def request_with_backoff(make_request, max_retries=5):
    for attempt in range(max_retries):
        response = make_request()

        if response.status_code == 429 or response.status_code >= 500:
            wait = min(2 ** attempt, 30) + random.uniform(0, 1)
            time.sleep(wait)
            continue

        return response

    raise Exception("Request failed after max retries")
```

| Attempt | Base delay | With jitter (example) |
| ------- | ---------- | --------------------- |
| 1       | 1s         | 1.0–2.0s              |
| 2       | 2s         | 2.0–3.0s              |
| 3       | 4s         | 4.0–5.0s              |
| 4       | 8s         | 8.0–9.0s              |
| 5       | 16s        | 16.0–17.0s            |

<Tip>
  If you run multiple workers or scheduled jobs, stagger their start times to avoid bursts of concurrent requests hitting the rate limit simultaneously.
</Tip>

For `429` responses, you can also read the `X-RateLimit-Remaining` header proactively to throttle before hitting the limit. See [Rate Limiting](/user-guide/rate-limiting) for details on quotas and headers.