Errors

Every failed request in Clopos Open API v2 returns a JSON body with a consistent shape. This page documents that envelope, the HTTP status codes you can expect, and the most common errors you will encounter in practice.

Error envelope

All error responses share the same top-level shape:

{
  "success": false,
  "message": "Human-readable summary of what went wrong",
  "error": "machine-readable error identifier"
}

Field	Type	Notes
`success`	boolean	Always `false` on error responses. Check this first rather than relying on status codes alone — the `test/production mismatch` response is returned with `200 OK` for historical reasons.
`message`	string	Free-form description suitable for logging or surfacing to an operator. Not intended to be parsed.
`error`	string	Present when the gateway or upstream produced a stable error identifier. Prefer matching on this when branching in code.

Always branch on success === false, not on the HTTP status code. One edge case — an integrator in test mode calling a production brand — is returned as 200 OK with success: false.

Status codes

Status	When you will see it
`200 OK`	Success. Also, unusually, the `test/production mismatch` rejection at `/v2/auth`.
`400 Bad Request`	Missing required fields, invalid `integrator_id`, or invalid parameters forwarded from the upstream Clopos API.
`401 Unauthorized`	Missing, invalid, or expired `x-token`; integrator disabled; test/production mismatch on authenticated endpoints; upstream auth rejected.
`404 Not Found`	The requested resource (receipt, customer, order, etc.) does not exist in the targeted brand + venue.
`429 Too Many Requests`	You exceeded the rate limit. See Rate limits.
`500 Internal Server Error`	Unhandled gateway error. These are reported to Sentry automatically; if you see them persistently, contact support with the timestamp and your `integrator_id`.
`504` / timeout	The upstream Clopos API did not respond within 8 seconds. Safe to retry idempotent requests.

Common errors

Missing `x-token`

HTTP/1.1 401 Unauthorized

{
  "success": false,
  "error": "Headers are missing"
}

You forgot to include the x-token header. Every v2 endpoint except /v2/auth requires it.

Invalid or malformed token

HTTP/1.1 401 Unauthorized

{
  "success": false,
  "error": "Invalid token"
}

The JWT is malformed or its signature does not verify. Do not retry — re-authenticate.

Expired token

HTTP/1.1 401 Unauthorized

{
  "success": false,
  "expires_at": "2026-01-01T12:00:00.000Z",
  "error": "Token expired"
}

The JWT has expired. Call /v2/auth again to obtain a fresh token, then retry the original request.

The expires_at in this error body is an ISO 8601 string, while the expires_at returned by /v2/auth is a Unix timestamp in seconds. Parse each accordingly.

Invalid `integrator_id` at `/v2/auth`

HTTP/1.1 400 Bad Request

{
  "success": false,
  "error": "Invalid integrator_id"
}

The integrator_id is not registered with Clopos or has been disabled. Request a new one via this form.

Test integrator hitting a production brand

HTTP/1.1 200 OK

{
  "success": false,
  "error": "Integrator is in test mode. But brand is not in test mode",
  "brand": "your_brand",
  "integrator": "your_integrator_name"
}

The integrator is flagged as test-only but you are trying to authenticate against a production brand. Either switch to a production integrator_id or target a non-production brand. See Core concepts → Test vs production integrators.

This one is the reason you should branch on success, not status code — it is returned as 200 OK at /v2/auth even though the authentication failed.

Missing required field at `/v2/auth`

HTTP/1.1 400 Bad Request

{
  "success": false,
  "error": "Missing client_id, client_secret, brand, or integrator_id"
}

One or more of the four required fields was omitted from the auth request body.

Resource not found

HTTP/1.1 404 Not Found

{
  "success": false,
  "message": "Not Found"
}

The requested resource does not exist in the targeted brand/venue combination. Double-check the ID and that the x-venue you are using (explicit header or JWT default) matches the venue where the resource lives.

Retry guidance

Status	Safe to retry?
`400`	No — fix the request first.
`401`	Only after re-authenticating.
`404`	No — the resource does not exist.
`429`	Yes, after the window indicated by `RateLimit-Reset`.
`500`	Yes, with exponential backoff. If it persists, contact support.
Timeout / `504`	Yes for idempotent requests (`GET`). For non-idempotent requests, check the server state first to avoid duplicates.

Reporting a bug

If you encounter an error you cannot explain, contact dev@clopos.com with:

The full request (method, URL, headers except x-token, and body).
The full response (status code, headers, body).
Your integrator_id and brand.
The approximate UTC timestamp.

These details let the Clopos team cross-reference the request in Sentry and upstream logs quickly.

Introduction

Concepts

Errors

Errors

Error envelope

Status codes

Common errors

Missing `x-token`

Invalid or malformed token

Expired token

Invalid `integrator_id` at `/v2/auth`

Test integrator hitting a production brand

Missing required field at `/v2/auth`

Resource not found

Retry guidance

Reporting a bug

​Errors

​Error envelope

​Status codes

​Common errors

​Missing x-token

​Invalid or malformed token

​Expired token

​Invalid integrator_id at /v2/auth

​Test integrator hitting a production brand

​Missing required field at /v2/auth

​Resource not found

​Retry guidance

​Reporting a bug

Errors

Error envelope

Status codes

Common errors

Missing `x-token`

Invalid or malformed token

Expired token

Invalid `integrator_id` at `/v2/auth`

Test integrator hitting a production brand

Missing required field at `/v2/auth`

Resource not found

Retry guidance

Reporting a bug