FusionDesk REST API Error Codes and Troubleshooting Guide

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.

{
  "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"
  }
}

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.

string

required

A human-readable description of the error. Suitable for logging and, in some cases, surfacing to end users.

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.

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.

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.
`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/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:

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.

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.

Overview

Endpoints

FusionDesk REST API Error Codes and Troubleshooting Guide

Error response structure

HTTP status codes

Error codes

Handling 429 rate limit errors

​Error response structure

​HTTP status codes

​Error codes

​Handling 429 rate limit errors

Error response structure

HTTP status codes

Error codes

Handling 429 rate limit errors