> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fusiondesk.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# FusionDesk REST API Error Codes and Troubleshooting Guide

> Understand FusionDesk REST API HTTP status codes, error response structure, and how to diagnose and resolve common API errors in your integration.

When a FusionDesk API request cannot be completed successfully, the API returns a structured error response alongside an appropriate HTTP status code. Understanding these codes and the shape of error payloads helps you build integrations that handle failures gracefully, surface meaningful messages to end users, and diagnose issues quickly.

## Error response structure

Every error response contains a top-level `error` object and a `meta` object. The `data` field is absent on error responses.

```json theme={null}
{
  "error": {
    "code": "invalid_field",
    "message": "The 'priority' field must be one of: low, medium, high, urgent.",
    "details": {
      "field": "priority",
      "provided_value": "critical"
    }
  },
  "meta": {
    "request_id": "req_abc123"
  }
}
```

<ResponseField name="error.code" type="string" required>
  A stable, machine-readable string that identifies the error type. Use this field in your error-handling logic — the `message` field is for humans and may change across releases.
</ResponseField>

<ResponseField name="error.message" type="string" required>
  A human-readable description of the error. Suitable for logging and, in some cases, surfacing to end users.
</ResponseField>

<ResponseField name="error.details" type="object | null">
  Optional structured data providing additional context about the error, such as which field failed validation and what value was provided. May be `null` when no additional context is available.
</ResponseField>

<ResponseField name="meta.request_id" type="string" required>
  A unique identifier for the request. Include this value when contacting FusionDesk support — it allows the support team to locate the exact request in the system logs.
</ResponseField>

## HTTP status codes

The API uses standard HTTP status codes to indicate the outcome of every request.

| Status | Meaning               | Common Cause                                                                                                                                      |
| ------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200`  | OK                    | The request succeeded and the response body contains the requested data.                                                                          |
| `201`  | Created               | A new resource was successfully created. The response body contains the created resource.                                                         |
| `400`  | Bad Request           | The request is malformed — a required field is missing, a parameter has an invalid type, or the JSON body cannot be parsed.                       |
| `401`  | Unauthorized          | The `Authorization` header is missing, the API key is invalid, or the key has been revoked.                                                       |
| `403`  | Forbidden             | The API key is valid but does not have permission to perform this action. Check the key's assigned scope.                                         |
| `404`  | Not Found             | The resource identified by the given ID does not exist, or the URL path is incorrect.                                                             |
| `409`  | Conflict              | The request conflicts with the current state of a resource — for example, attempting to create a resource that already exists.                    |
| `422`  | Unprocessable Entity  | The request body is syntactically valid JSON but fails business-logic validation (e.g. an enum field contains an unrecognised value).             |
| `429`  | Too Many Requests     | Your integration has exceeded the rate limit of 1,000 requests per minute. See [Handling 429 rate limit errors](#handling-429-rate-limit-errors). |
| `500`  | Internal Server Error | An unexpected error occurred on FusionDesk's servers. If this persists, contact support with your `request_id`.                                   |

## Error codes

In addition to HTTP status codes, the `error.code` field provides a stable string you can match in your code.

| Code            | Associated Status | Description                                                                                                                         |
| --------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_field` | 400 / 422         | A field in the request body contains an invalid value or fails validation. Check `error.details` for the offending field and value. |
| `missing_field` | 400               | A required field is absent from the request body or query parameters.                                                               |
| `unauthorized`  | 401               | The API key is missing, malformed, invalid, or revoked.                                                                             |
| `forbidden`     | 403               | The API key does not have the scope required to perform this action.                                                                |
| `not_found`     | 404               | The requested resource ID does not exist in the system.                                                                             |
| `conflict`      | 409               | The operation conflicts with the current state of an existing resource.                                                             |
| `rate_limited`  | 429               | The request was rejected because the rate limit was exceeded.                                                                       |
| `server_error`  | 500               | An internal error occurred. Retry the request after a short delay; if the issue persists, contact support.                          |

## Handling 429 rate limit errors

When your integration exceeds 1,000 requests per minute, the API responds with HTTP `429` and a `Retry-After` header. The value of `Retry-After` is an integer representing the number of seconds to wait before retrying.

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 8
Content-Type: application/json

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Please retry after 8 seconds.",
    "details": null
  },
  "meta": { "request_id": "req_abc123" }
}
```

Always implement **exponential backoff with jitter** for retry logic rather than retrying at a fixed interval. The example below shows a simple retry wrapper in JavaScript:

```javascript theme={null}
async function fetchWithRetry(url, options, maxRetries = 4) {
  let attempt = 0;

  while (attempt <= maxRetries) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    const retryAfter = parseInt(response.headers.get('Retry-After') ?? '1', 10);
    const jitter = Math.random() * 1000; // up to 1 second of random jitter
    const delay = retryAfter * 1000 + jitter;

    console.warn(`Rate limited. Retrying in ${Math.round(delay)}ms (attempt ${attempt + 1}/${maxRetries})`);
    await new Promise(resolve => setTimeout(resolve, delay));

    attempt++;
  }

  throw new Error('Max retries exceeded after repeated 429 responses.');
}
```

To reduce the likelihood of hitting rate limits, consider caching frequently read resources, batching write operations where the API supports it, and spreading scheduled jobs across time rather than triggering them simultaneously.

<Tip>
  Whenever you contact FusionDesk support about an unexpected API error, include the `meta.request_id` value from the error response. This identifier lets the support team retrieve the exact server-side logs for your request, which dramatically speeds up diagnosis and resolution.
</Tip>