> For the complete documentation index, see [llms.txt](https://hub.equipme.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hub.equipme.io/development/error-handling.md).

# Error Handling

### Error Categories and Response Strategy

<table><thead><tr><th width="134">HTTP Status</th><th width="140">Category</th><th>Meaning</th><th width="92">Retry?</th><th>Notes</th></tr></thead><tbody><tr><td><strong>400 Bad Request</strong></td><td>Input Error</td><td>Request contains invalid or malformed data (validation errors, incorrect values, wrong format)</td><td>No</td><td>Fix request before retrying</td></tr><tr><td><strong>401 Unauthorized</strong></td><td>Authentication</td><td>API key is missing, invalid, expired, or revoked</td><td>No</td><td>Update credentials</td></tr><tr><td><strong>403 Forbidden</strong></td><td>Authorization</td><td>Valid authentication but insufficient permissions for this resource or endpoint</td><td>No</td><td>Check tenant type and permissions</td></tr><tr><td><strong>404 Not Found</strong></td><td>Resource</td><td>Resource doesn't exist or you don't have access to it</td><td>No</td><td>Verify resource ID; may be deleted</td></tr><tr><td><strong>409 Conflict</strong></td><td>Business Logic</td><td>Operation cannot be performed due to resource state or business rules (e.g., editing closed order, deleting resource with dependencies)</td><td>No</td><td>Review resource state and requirements</td></tr><tr><td><strong>429 Too Many Requests</strong></td><td>Rate Limit</td><td>Rate limit exceeded</td><td>Yes</td><td>Wait for <code>Retry-After</code> seconds</td></tr><tr><td><strong>500 Internal Server Error</strong></td><td>Server</td><td>Unexpected server error</td><td>Yes</td><td>Retry with exponential backoff</td></tr><tr><td><strong>502 Bad Gateway</strong></td><td>Server</td><td>Upstream service error</td><td>Yes</td><td>Retry with exponential backoff</td></tr><tr><td><strong>503 Service Unavailable</strong></td><td>Server</td><td>Temporary unavailability</td><td>Yes</td><td>Retry with exponential backoff</td></tr></tbody></table>

**Key Principles:**

* **4xx errors** - Client-side issues; fix the request before retrying
* **5xx errors** - Server-side issues; safe to retry with backoff
* **429** - Always respect the `Retry-After` header

***

### Error Response Format

When an error occurs, the API returns a consistent JSON structure:

json

```json
{
  "errorCode": "AuthenticationFailed",
  "errorDescription": "API key has expired. Please generate a new key."
}
```

#### Fields

| Field              | Type   | Description                                                   |
| ------------------ | ------ | ------------------------------------------------------------- |
| `errorCode`        | string | Machine-readable error identifier                             |
| `errorDescription` | string | Human-readable description in English                         |
| `data`             | object | Optional. Additional context (structure varies by error type) |

#### Extended Error Data

Some errors include additional context in the `data` field. The structure depends on the error type.

**Validation errors with field-level details:**

json

```json
{
  "errorCode": "ValidationError",
  "errorDescription": "Email must be a valid e-mail address.\nFirstName must not exceed 100 characters.",
  "data": {
    "errors": [
      {
        "field": "Email",
        "errorMessage": "Email must be a valid e-mail address."
      },
      {
        "field": "FirstName",
        "errorMessage": "FirstName must not exceed 100 characters."
      }
    ]
  }
}
```

{% hint style="info" %}
The `data` field structure is dynamic and varies depending on the error type. Parse it flexibly to handle different formats.
{% endhint %}

***

### Error Codes Reference

The string `errorCode` in the error response object contains of the following values.

#### Authentication & Authorization

<table><thead><tr><th width="221">Error Code</th><th width="144">HTTP Status</th><th>Description</th></tr></thead><tbody><tr><td><code>Unauthorized</code></td><td>401</td><td>API key is missing, invalid, expired, or revoked</td></tr><tr><td><code>AuthenticationFailed</code></td><td>401</td><td>Authentication credentials are invalid</td></tr><tr><td><code>Forbidden</code></td><td>403</td><td>Valid authentication but insufficient permissions</td></tr><tr><td><code>AccessDenied</code></td><td>403</td><td>Access to this resource is denied</td></tr></tbody></table>

#### Resource Errors

<table><thead><tr><th width="250">Error Code</th><th width="148">HTTP Status</th><th>Description</th></tr></thead><tbody><tr><td><code>NotFound</code></td><td>404</td><td>Resource not found or inaccessible</td></tr><tr><td><code>ResourceHasBeenRemoved</code></td><td>404</td><td>Resource has been removed/archived</td></tr><tr><td><code>AlreadyExists</code></td><td>409</td><td>Resource with this identifier already exists</td></tr></tbody></table>

#### Validation Errors

<table><thead><tr><th width="216">Error Code</th><th width="138">HTTP Status</th><th>Description</th></tr></thead><tbody><tr><td><code>ValidationError</code></td><td>400</td><td>Request contains invalid data (see <code>data.errors</code> for details)</td></tr><tr><td><code>InvalidParameter</code></td><td>400</td><td>One or more parameters are invalid</td></tr><tr><td><code>InvalidFileType</code></td><td>400</td><td>Uploaded file type is not supported</td></tr><tr><td><code>InvalidFileSize</code></td><td>400</td><td>Uploaded file exceeds size limit</td></tr><tr><td><code>InvalidImageFormat</code></td><td>400</td><td>Image format is not supported</td></tr><tr><td><code>InvalidHeader</code></td><td>400</td><td>Header value is invalid</td></tr><tr><td><code>DuplicateEmail</code></td><td>400</td><td>Email address / username is already in use</td></tr><tr><td><code>LimitExceeded</code></td><td>400</td><td>Can't add further resources of this type in the context (e.g. amount of images per product)</td></tr></tbody></table>

#### Business Logic Errors

<table><thead><tr><th width="278">Error Code</th><th width="134">HTTP Status</th><th>Description</th></tr></thead><tbody><tr><td><code>Conflict</code></td><td>409</td><td>Request conflicts with current state</td></tr><tr><td><code>InvalidTransition</code></td><td>409</td><td>State transition is not permitted</td></tr><tr><td><code>InvalidContext</code></td><td>409</td><td>Operation not valid in current context</td></tr><tr><td><code>InvalidOrderTransactionType</code></td><td>409</td><td>Order transaction type is not valid for this operation</td></tr><tr><td><code>IsOwnAccount</code></td><td>409</td><td>Operation cannot be performed on your own account</td></tr><tr><td><code>IsBomItem</code></td><td>409</td><td>Operation restricted due to BOM (Bill of Materials) relationship</td></tr><tr><td><code>IsReferred</code></td><td>409</td><td>Resource is referenced by other resources</td></tr><tr><td><code>MissingDependency</code></td><td>409</td><td>Required dependency is missing</td></tr><tr><td><code>RemainingDependencies</code></td><td>409</td><td>Resource has remaining dependencies preventing operation</td></tr><tr><td><code>AssignedServices</code></td><td>409</td><td>Resource has assigned services preventing operation</td></tr></tbody></table>

#### Rate Limiting

<table><thead><tr><th width="210">Error Code</th><th width="173">HTTP Status</th><th>Description</th></tr></thead><tbody><tr><td><code>TooManyRequests</code></td><td>429</td><td>Rate limit exceeded</td></tr></tbody></table>

#### Server Errors

<table><thead><tr><th width="199">Error Code</th><th width="180">HTTP Status</th><th>Description</th></tr></thead><tbody><tr><td><code>UnexpectedError</code></td><td>500</td><td>Unexpected server error occurred</td></tr></tbody></table>

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hub.equipme.io/development/error-handling.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.