Error Handling

Error Categories and Response Strategy

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

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

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

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

The data field structure is dynamic and varies depending on the error type. Parse it flexibly to handle different formats.

---

Error Codes Reference

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

Authentication & Authorization

Error Code	HTTP Status	Description
Unauthorized	401	API key is missing, invalid, expired, or revoked
AuthenticationFailed	401	Authentication credentials are invalid
Forbidden	403	Valid authentication but insufficient permissions
AccessDenied	403	Access to this resource is denied

Resource Errors

Error Code	HTTP Status	Description
NotFound	404	Resource not found or inaccessible
ResourceHasBeenRemoved	404	Resource has been removed/archived
AlreadyExists	409	Resource with this identifier already exists

Validation Errors

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

Business Logic Errors

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

Rate Limiting

Error Code	HTTP Status	Description
TooManyRequests	429	Rate limit exceeded

Server Errors

Error Code	HTTP Status	Description
UnexpectedError	500	Unexpected server error occurred

---