Responses & Errors

Every response uses the same envelope, whether it succeeded or not.

Field	Type	Description
`success`	boolean	Whether the request did what you asked
`message`	string \| null	Human-readable detail, usually `null` on success
`code`	string \| null	Error code when something failed, otherwise `null`
`data`	object \| array \| null	The payload

{
  "success": true,
  "message": null,
  "code": null,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Store"
  }
}

Branch on success, not on the status code alone, and read code rather than message when handling failures. Messages are written for humans and can be reworded; codes are stable.

List responses

Endpoints returning a list add pages: how many pages exist at the current page size. There’s no total item count, so page until you reach it.

{
  "success": true,
  "pages": 5,
  "data": [
    // items
  ]
}

See Filtering & Sorting for narrowing, ordering and paging those results.

Errors

{
  "success": false,
  "message": "Access denied.",
  "code": "AccessDenied",
  "data": null
}

code is a stable PascalCase identifier: AccessDenied, NotFound, ObjectConflict, ValidationError, UpgradeRequired and so on.

Validation errors

Validation failures add invalidFields, one entry per problem, each formatted Field: what's wrong:

{
  "success": false,
  "message": "Validation failed",
  "code": "ValidationError",
  "data": null,
  "invalidFields": ["Name: Must be between 3 and 64 characters"]
}

Surface these to whoever submitted the data - they name the field and the rule it broke.

HTTP status codes

Status	Usually means
`400`	Malformed request, or validation failed
`401`	Missing, malformed or revoked API key
`403`	Valid key, but it lacks the scope for this endpoint
`404`	Wrong ID, or a resource on an account you can’t reach
`409`	Conflicts with something that already exists
`429`	Too many requests
`5xx`	Our side

Retrying

Retry 429 and 5xx with increasing delays rather than immediately. Don’t retry 4xx responses other than 429 - the request will fail the same way until you change it. If a 5xx persists, check status.komerza.com before digging into your own code.

Every error code

The full list of code values, what triggers each and how to recover.

Last modified on August 2, 2026

Conventions

Filtering & Sorting

API Documentation

Reference

OAuth2

User

Stores

Products

Categories

Variants

Coupons

Tickets

Customers

Orders

Reviews

Affiliates

Webhooks

List responses

Errors

Validation errors

HTTP status codes

Retrying

Every error code

​List responses

​Errors

​Validation errors

​HTTP status codes

​Retrying

Every error code

List responses

Errors

Validation errors

HTTP status codes

Retrying