Error handling

This page describes the HTTP status codes, the error response format, and best practices for handling errors in the Flixer Pro API.

HTTP status codes

Code	Status	Description
200	OK	The request was processed successfully
201	Created	The resource was created successfully
400	Bad Request	The request contains invalid or missing parameters (validation error)
401	Unauthorized	The `X-API-Key` header is missing, or the key is invalid or revoked
403	Forbidden	The key lacks the required scope for this endpoint
404	Not Found	The requested resource does not exist
429	Too Many Requests	The rate limit has been exceeded — try again later
500	Internal Server Error	An unexpected server error occurred

Error response format

Error responses follow the standard NestJS format with three fields:

{
  "statusCode": 400,
  "message": "customerName is required",
  "error": "Bad Request"
}

Fields:

statusCode — The HTTP status code (matches the response status)
message — A human-friendly error description. For validation errors this can be an array of strings (one per field that fails)
error — The HTTP status text (e.g. Bad Request, Unauthorized)

Every response also includes an X-Request-Id header. Keep this value and mention it in support requests — it makes it possible to trace the request on the server side.

Common errors

400 — Bad Request (Validation error)

Causes:

A required field is missing (e.g. customerName or title when creating a lead)
A field value does not meet the rules (e.g. a field that is too long)

Solutions:

Read the message field of the response — it describes which field is causing the problem
Validate required fields on the client side before sending them
Consult the endpoint documentation for the field requirements

401 — Unauthorized (Not Authenticated)

Causes:

The X-API-Key header is missing from the request
The API key is invalid or has been revoked

Solutions:

Make sure you send the header:
X-API-Key: your_api_key
Check that the key has not been revoked in Settings > API keys
Create a new key if needed

403 — Forbidden (Insufficient Scope)

Causes:

The key is valid, but lacks the scope this endpoint requires (e.g. leads:write for creating a lead)

Solutions:

Check which scope the endpoint requires (see Authentication)
Create a key with the correct scopes, or use a key with the full scope

429 — Too Many Requests (Rate Limit)

Causes:

Too many requests were sent in a short period

Solutions:

Implement retry logic with exponential backoff (see below)
Reduce the frequency of your requests; do not poll more often than necessary

500 — Internal Server Error (Server Error)

Causes:

An unexpected error in the server application

Solutions:

These errors are usually temporary — implement retry logic with exponential backoff
Wait a few seconds and try again
If the problem persists, mention the X-Request-Id to the support team

Error handling in code

JavaScript/TypeScript

interface ApiError {
  statusCode: number;
  message: string | string[];
  error: string;
}

async function createLead(payload: Record<string, unknown>) {
  const response = await fetch("https://api.flixerpro.io/v1/api/leads", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.FLIXER_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  });

  if (!response.ok) {
    const err = (await response.json()) as ApiError;
    const requestId = response.headers.get("X-Request-Id");

    switch (response.status) {
      case 400:
        console.error("Validation error:", err.message);
        break;
      case 401:
        console.error("Invalid or missing API key");
        break;
      case 403:
        console.error("Key lacks the required scope");
        break;
      default:
        console.error(`API error ${response.status} (request ${requestId})`);
    }
    throw new Error(
      Array.isArray(err.message) ? err.message.join(", ") : err.message,
    );
  }

  return response.json();
}

Python

import os
import requests

class FlixerAPIError(Exception):
    def __init__(self, status_code: int, body: dict):
        self.status_code = status_code
        self.body = body
        super().__init__(body.get("message", "Unknown error"))

def create_lead(payload: dict) -> dict:
    response = requests.post(
        "https://api.flixerpro.io/v1/api/leads",
        headers={
            "X-API-Key": os.environ["FLIXER_API_KEY"],
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=30,
    )

    if not response.ok:
        body = response.json()
        request_id = response.headers.get("X-Request-Id")
        print(f"API error {response.status_code} (request {request_id}): {body.get('message')}")
        raise FlixerAPIError(response.status_code, body)

    return response.json()

Retry strategy

Implement exponential backoff for 5xx errors and 429:

Attempt 1: Immediately
Attempt 2: Wait 1 second
Attempt 3: Wait 2 seconds
Attempt 4: Wait 4 seconds

async function fetchWithRetry(
  url: string,
  options: RequestInit,
  maxRetries = 3,
  baseDelay = 1000,
): Promise<Response> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    // Only 5xx and 429 are worth a retry
    if (response.ok || (response.status < 500 && response.status !== 429)) {
      return response;
    }

    if (attempt < maxRetries - 1) {
      // Backoff with jitter to prevent a "thundering herd"
      const delay = baseDelay * 2 ** attempt + Math.random() * 1000;
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
  throw new Error("Max retries reached");
}

Only repeat requests when it is safe to do so. GET requests are idempotent and always safe to repeat. Be careful with POST /leads: only repeat after a 5xx or a network error (where the lead probably was not created), not after a 400/401/403.

Best practices

Always check response.ok — do not assume every request succeeds
Read the message field — on a 400 it tells you exactly what went wrong
Keep the X-Request-Id — indispensable for support requests
Exponential backoff — for 5xx and 429, with jitter
Set timeouts — prevent requests from hanging indefinitely
Use minimal scopes — limit the impact if a key leaks

Getting started

Guides

Reference

Error handling

Error handling

HTTP status codes

Error response format

Common errors

400 — Bad Request (Validation error)

401 — Unauthorized (Not Authenticated)

403 — Forbidden (Insufficient Scope)

429 — Too Many Requests (Rate Limit)

500 — Internal Server Error (Server Error)

Error handling in code

JavaScript/TypeScript

Python

Retry strategy

Best practices

​Error handling

​HTTP status codes

​Error response format

​Common errors

​400 — Bad Request (Validation error)

​401 — Unauthorized (Not Authenticated)

​403 — Forbidden (Insufficient Scope)

​429 — Too Many Requests (Rate Limit)

​500 — Internal Server Error (Server Error)

​Error handling in code

​JavaScript/TypeScript

​Python

​Retry strategy

​Best practices

Error handling

HTTP status codes

Error response format

Common errors

400 — Bad Request (Validation error)

401 — Unauthorized (Not Authenticated)

403 — Forbidden (Insufficient Scope)

429 — Too Many Requests (Rate Limit)

500 — Internal Server Error (Server Error)

Error handling in code

JavaScript/TypeScript

Python

Retry strategy

Best practices