Errors - 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:

{
  "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.	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 the error field 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:
    error_message = response.json().get("error", "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}`);
}

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.

​Error response body

​Status codes

​Handling errors in code

​Retry strategy

Error response body

Status codes

Handling errors in code

Retry strategy