Error Handling

External App API responses use a common envelope:

{
  "success": false,
  "data": null,
  "error": {
    "title": "Request could not be completed",
    "status": 422,
    "detail": "The request failed a business rule.",
    "errorCode": "ERROR_CODE"
  },
  "timestamp": "2026-01-01T12:00:00Z"
}

Check both the HTTP status and the response's success field. When success is false, use error.errorCode for program logic and error.detail for diagnostics. Do not expose internal diagnostic details directly to end users.

Status	Meaning	Recommended handling
400	Missing or invalid request data	Correct the request; do not retry unchanged.
401	Invalid or expired external app session	Stop requests and restore valid partner credentials.
403	The integration lacks permission	Refresh linked resources and ask the customer to verify access.
404	Pairing code, site, entry point, controller, or command was not found	Refresh local mappings or ask the customer to start pairing again.
422	A business rule prevented the operation	Show an actionable message based on the problem details.
500	KINDOO could not complete the request	Retry read operations with exponential backoff; avoid blindly retrying commands.

Retry policy

• Retry transient failures with exponential backoff and jitter.
• Do not retry 400, 401, 403, or 422 responses without changing the request or application state.
• Reads are safe to retry. Treat command creation as non-idempotent unless your integration agreement states otherwise.
• Set request deadlines and a maximum number of attempts.

Logging

Log the endpoint, HTTP status, errorCode, and response timestamp needed for support. Never log SessionTokenID, pairing codes, or other credentials.

For asynchronous command failures, also log the CommandID, numeric Status, and StatusDescription so the operation can be traced without exposing credentials.