When interacting with the Public API, it's important to understand how errors are communicated and how to handle them effectively. This guide explains the error structure, common error codes, and provides tips for troubleshooting.

Error Response Structure

Every failed request to the API returns a structured error response in JSON format. The typical error response includes the following fields:

{
  "statusCode": 400,
  "errorId": "bad_request",
  "errorDetails": null,
  "path": "/api/v1/organizations/0",
  "requestId": "1112223334445556667"
}

interface ErrorResponse {
  statusCode: number;
  errorId: string;
  errorDetails: unknown;
  path: string;
  requestId: string;
}

Let's break it down:

statusCode: HTTP Status code, corresponds to the status code of the response.
errorId: A unique identifier for tracking the error, which can be used for debugging or reporting issues to support. It is either a custom error, e.g. api_key_creator_removed, or a stringified version of the HTTP Status code, e.g. bad_request in case of HTTP Status code 400.
errorDetails: It may contain additional details about the error, e.g. if validation fails, it will contain the reason, e.g. missing fields. It is null by default.
path: The request URL that generated the error.
requestId: ID of the request.

Common HTTP Status Codes:

400 Bad Request: The request was malformed and could not be parsed.
401 Unauthorized: The API key was missing or invalid.
403 Access Denied: The API key does not have the necessary permissions.
404 Not found:The requested resource was not found.
408 Request Timeout: The request took too long, the server closed the connection.
409 Conflict: This error usually indicates that a resource with the same unique identifier already exists.
418 I'm a teapot: This unusual error code means the endpoint is using a feature that your organization doesn't have access to. Please try again or contact our Support team for assistance in resolving this issue.
422 Unprocessable Entity: The request was parseable (i.e. valid JSON), but some parameters were missing or otherwise invalid.
429 Too Many Requests: The client has exceeded the allowed number of requests and has been temporarily throttled. Check the response headers for more information.
500 Internal Server Error: System error.

Admina `ErrorId`:

validation_exception: Indicates that the request was rejected due to validation errors. Please see the errorDetailsproperty for more details.
api_key_creator_removed: The owner of the API key used to make the request has been removed from the organization.
organization_suspended: The organization has been suspended. Please reactivate it by subscribing.
workspace_already_exists: A workspace with the same service and aggregation key already exists.
custom_workspace_already_exists: A custom workspace with the same service and aggregation key already exists.
duplicated_aggre_request: A similar request has already been registered and is currently being processed.
identity_duplicated_email: An identity with the same email already exists.
identity_has_workspace: The identity cannot be archived because they are part of a workspace.
identity_has_devices: The identity cannot be archived because they have an assigned device.
identity_invalid_employee_type: An invalid employee type was provided when creating or updating the identity.
identity_duplicate_employee_id: An employee with the same ID already exists.
too_many_requests: The client has exceeded the allowed number of requests and has been temporarily throttled. Check the response headers for more information.