Errors

The Customer API uses standard HTTP status codes and returns errors in two different formats, depending on the endpoint.

Standard format

Most endpoints return errors in this shape:

{ "error": "Human-readable message describing what went wrong." }

The error field is a single, plain-English message intended for display in logs and operator dashboards. There is no separate error code field — the HTTP status code is authoritative.

OAuth format

The /auth/token endpoint follows the OAuth 2.0 error format:

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials."
}

Field	Description
error	A short OAuth error code (e.g. invalid_client, unsupported_grant_type).
error_description	A human-readable message.

See Authentication — Error responses for the full list of OAuth error codes.

Status codes used

Status	Meaning	Typical cause
200 OK	Success	Request succeeded with a response body.
400 Bad Request	Client error	The request is malformed — missing required field, wrong content type, etc.
401 Unauthorized	Authentication failed	Missing, malformed, or expired access token, or invalid client credentials on /auth/token.
404 Not Found	Resource not found	Your customer record could not be found.
429 Too Many Requests	Rate-limited	See Rate limits.
500 Internal Server Error	Server error	Something went wrong on our side. Please retry; if it persists, contact support.

Common error responses

401 Unauthorized — protected endpoints

Bearer-token validation failures (missing, malformed, or expired tokens) return 401 with no response body and a WWW-Authenticate header:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token"

Fix: Request a new token from /auth/token.

401 Unauthorized — /auth/token

Invalid client credentials on the token endpoint return the OAuth format:

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials."
}

Fix: Verify your Customer Code and API Key. If the key has been rotated or revoked, contact your Kiss account manager.

400 Bad Request — /auth/token

For malformed token requests, the response uses the OAuth format:

{ "error": "unsupported_grant_type", "error_description": "Only 'client_credentials' grant type is supported." }

{ "error": "invalid_request", "error_description": "client_id and client_secret are required." }

404 Not Found

The customer record for the authenticated token could not be located:

{ "error": "Customer not found." }

Fix: This usually indicates an account problem rather than a client bug. Contact support.

429 Too Many Requests

You've exceeded your rate-limit window. See Rate limits for the response shape and how to handle it.

500 Internal Server Error

{ "error": "An unexpected error occurred." }

Fix: Retry once after a short delay. If the error persists, open a support ticket with the time of the request and your Customer Code so we can investigate.

Error-handling pattern

A robust client should treat HTTP errors as a small, finite set:

- 2xx → success path
- 401 → refresh token, retry once
- 429 → wait Retry-After, retry with back-off
- 4xx (other) → permanent failure, log and surface
- 5xx → transient failure, retry with back-off

This pattern works for almost all integrations. Resist the temptation to inspect the error text — it's intended for humans, and the wording may change between releases.

What we never include in errors

For security reasons, error responses never include:

• Stack traces.
• Internal IDs that aren't already in the request URL.
• The exact set of valid values for a field you got wrong (you must consult the documentation).

If you believe an error message is so unclear that it's blocking your work, please open a support ticket and we'll improve it in a future release.