Error Codes and HTTP Responses in the Fliqr AI API

Fliqr AI uses standard HTTP status codes to indicate whether a request succeeded or failed. Every error response — regardless of the cause — returns the same JSON object shape, so you can write a single error-handling layer in your application rather than parsing different formats per endpoint.

Error Object Shape

All error responses include a top-level error object:

{
  "error": {
    "code": "string",
    "message": "string",
    "param": "string | null",
    "doc_url": "string | null"
  }
}

string

A machine-readable error identifier. Use this in your application logic to branch on specific failure types. See the full table below.

string

A human-readable description of what went wrong. Suitable for logging; do not display raw API error messages directly to end users without sanitizing.

string | null

When present, identifies the specific request parameter that caused the error. Always check this field on 400 and 422 responses to pinpoint the failing field.

string | null

A link to the relevant documentation section for this error code. May be null if no additional documentation is available.

Error Code Reference

Status	Code	Meaning
400	`bad_request`	Request body is malformed or a required parameter is missing
400	`validation_error`	A parameter failed validation (see `param` field)
401	`unauthorized`	API key is missing or invalid
403	`forbidden`	API key does not have permission for this resource
404	`not_found`	The resource does not exist
409	`conflict`	Duplicate resource (e.g., contact with phone number already exists)
422	`unprocessable`	Request is valid but cannot be processed in current state
429	`rate_limit_exceeded`	Too many requests
500	`internal_error`	Unexpected server error — retry with exponential backoff
503	`service_unavailable`	Platform is temporarily unavailable

Common Error Scenarios

400 — Bad Request or Validation Error

Returned when the request body cannot be parsed or a field fails a validation rule. Check the param field to identify which parameter is invalid:

{
  "error": {
    "code": "validation_error",
    "message": "The 'phone' field must be in E.164 format.",
    "param": "phone",
    "doc_url": "https://docs.fliqr.ai/api-reference/contacts"
  }
}

401 — Unauthorized

Your API key is absent, malformed, or revoked. Verify that the Authorization: Bearer YOUR_API_KEY header is present and that the key is still active in Settings → API.

403 — Forbidden

Your key is valid but does not have access to the requested resource. This can occur when a key is scoped to specific resources or when you attempt to access a resource that belongs to a different account.

404 — Not Found

The resource ID in the URL path does not exist. Verify the ID is correct and that the resource has not been deleted.

409 — Conflict

A duplicate resource already exists. For example, attempting to create a contact with a phone number that already belongs to an existing contact. The existing resource ID is usually included in the error message.

422 — Unprocessable

The request is syntactically valid but cannot be executed given the current state of the system. For example, triggering a WhatsApp flow for a contact who has never interacted on WhatsApp. Inspect the message field for the specific reason.

429 — Rate Limit Exceeded

You have exceeded your request budget. Read the retry_after field and wait before retrying. See the Rate Limits guide for backoff strategies.

500 — Internal Error

An unexpected error occurred on the Fliqr AI platform. These are rare. Retry using exponential backoff (starting at 1 second, doubling up to a maximum of 32 seconds). If the error persists beyond a few minutes, check the status page.

503 — Service Unavailable

The platform is temporarily unavailable, typically during a brief maintenance window or traffic spike. Treat this the same as a 500 — retry with backoff and monitor the status page.

Subscribe to the Fliqr AI status page for real-time uptime monitoring and incident updates. During an active incident, retrying aggressively can worsen recovery time for all users.

Handling Errors in Code

Structure your API client to handle errors at the HTTP layer before inspecting the response body:

async function fliqrRequest(path, options = {}) {
  const res = await fetch(`https://api.fliqr.ai/v1${path}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${process.env.FLIQR_API_KEY}`,
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });

  if (!res.ok) {
    const { error } = await res.json();
    // Log structured error for observability
    console.error(`[Fliqr AI] ${error.code}: ${error.message}`, {
      param: error.param,
      status: res.status,
    });
    throw new Error(error.message);
  }

  return res.json();
}

Overview

Accounts

Contacts

AI Agents

Pipelines

Ecommerce

Appointment Management

Templates

Error Codes and HTTP Responses in the Fliqr AI API

Error Object Shape

Error Code Reference

Common Error Scenarios

400 — Bad Request or Validation Error

401 — Unauthorized

403 — Forbidden

404 — Not Found

409 — Conflict

422 — Unprocessable

429 — Rate Limit Exceeded

500 — Internal Error

503 — Service Unavailable

Handling Errors in Code

What’s Next

Authentication

Rate Limits

​Error Object Shape

​Error Code Reference

​Common Error Scenarios

​400 — Bad Request or Validation Error

​401 — Unauthorized

​403 — Forbidden

​404 — Not Found

​409 — Conflict

​422 — Unprocessable

​429 — Rate Limit Exceeded

​500 — Internal Error

​503 — Service Unavailable

​Handling Errors in Code

​What’s Next

Authentication

Rate Limits

Error Object Shape

Error Code Reference

Common Error Scenarios

400 — Bad Request or Validation Error

401 — Unauthorized

403 — Forbidden

404 — Not Found

409 — Conflict

422 — Unprocessable

429 — Rate Limit Exceeded

500 — Internal Error

503 — Service Unavailable

Handling Errors in Code

What’s Next