> ## Documentation Index
> Fetch the complete documentation index at: https://fliqr.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Error Codes and HTTP Responses in the Fliqr AI API
> A complete reference for every HTTP status code and error object the Fliqr AI API returns, with guidance on how to handle each case.
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:
```json theme={null}
{
"error": {
"code": "string",
"message": "string",
"param": "string | null",
"doc_url": "string | null"
}
}
```
A machine-readable error identifier. Use this in your application logic to branch on specific failure types. See the full table below.
A human-readable description of what went wrong. Suitable for logging; do not display raw API error messages directly to end users without sanitizing.
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.
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:
```json theme={null}
{
"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](/docs/api-reference/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](https://status.fliqr.ai) 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:
```javascript theme={null}
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();
}
```
***
## What's Next
Ensure your API key is set up correctly to avoid 401 and 403 errors.
Learn how to handle 429 responses and implement backoff strategies.