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:

{
  "error": "descriptive error message"
}

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.

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.	Yes — after a backoff.
500	Internal Server Error	An unexpected issue on the Everflow side.	Yes — with backoff. If persistent, contact Support.
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.

# 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

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}")

Node.js

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:

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

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

For 429 responses, you can also read the X-RateLimit-Remaining header proactively to throttle before hitting the limit. See Rate Limiting for details on quotas and headers.