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

All error responses return a JSON object with a single `error` field containing a human-readable message:

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

This structure is consistent across all error status codes. Parse the `error` field to display or log the reason for failure.

## 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 `No Authentication Method Found`), invalid or revoked API key.                                                  | 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 the `error` field 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:
    error_message = response.json().get("error", "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}`);
}
```

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