Error Handling

The Servicebay API uses standard HTTP status codes and returns detailed error messages.

Error Response Format

{
  "success": false,
  "error": "Description of what went wrong"
}

HTTP Status Codes

Status Code	Meaning	Description
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`400`	Bad Request	Invalid request parameters or body
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Valid key but no access to resource
`404`	Not Found	Resource doesn't exist
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Something went wrong on our end

Common Errors

401 Unauthorized

{
  "success": false,
  "error": "Missing API key. Include X-API-Key header in your request."
}

Solution: Include a valid API key in the X-API-Key header.

403 Forbidden

{
  "success": false,
  "error": "You do not have access to this organisation"
}

Solution: Your API key is scoped to a different organisation. Use the correct key for the organisation you're trying to access.

404 Not Found

{
  "success": false,
  "error": "Customer not found"
}

Solution: Check that the resource ID is correct.

429 Rate Limited

{
  "success": false,
  "error": "Rate limit exceeded. Please wait before making more requests."
}

Solution: Wait until the rate limit window resets (see X-RateLimit-Reset header).

Handling Errors in Code

async function makeApiRequest(url, options) {
  const response = await fetch(url, {
    ...options,
    headers: {
      "X-API-Key": API_KEY,
      "Content-Type": "application/json",
      ...options.headers,
    },
  });

  const data = await response.json();

  if (!data.success) {
    switch (response.status) {
      case 401:
        throw new Error("Invalid API key");
      case 403:
        throw new Error("Access denied to this resource");
      case 404:
        throw new Error("Resource not found");
      case 429:
        const resetTime = response.headers.get("X-RateLimit-Reset");
        throw new Error(`Rate limited. Retry after ${resetTime}`);
      default:
        throw new Error(data.error || "Unknown error");
    }
  }

  return data;
}

Error Handling

On this page