Skip to main content

​
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"
}
FieldTypeNotes
successbooleanAlways 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.
messagestringFree-form description suitable for logging or surfacing to an operator. Not intended to be parsed.
errorstringPresent 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

StatusWhen you will see it
200 OKSuccess. Also, unusually, the test/production mismatch rejection at /v2/auth.
400 Bad RequestMissing required fields, invalid integrator_id, or invalid parameters forwarded from the upstream Clopos API.
401 UnauthorizedMissing, invalid, or expired x-token; integrator disabled; test/production mismatch on authenticated endpoints; upstream auth rejected.
404 Not FoundThe requested resource (receipt, customer, order, etc.) does not exist in the targeted brand + venue.
429 Too Many RequestsYou exceeded the rate limit. See Rate limits.
500 Internal Server ErrorUnhandled gateway error. These are reported to Sentry automatically; if you see them persistently, contact support with the timestamp and your integrator_id.
504 / timeoutThe 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

StatusSafe to retry?
400No — fix the request first.
401Only after re-authenticating.
404No — the resource does not exist.
429Yes, after the window indicated by RateLimit-Reset.
500Yes, with exponential backoff. If it persists, contact support.
Timeout / 504Yes 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 [email protected] 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.