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:

{
  "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, invalid or revoked API key.	No — check your key.
403	Forbidden	Wrong API key type for the endpoint (e.g. 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.

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.