Skip to main content
KalinkloOS
Developer documentation

Developer portal

Telemetry and Status

Request IDs, the error envelope, the HTTP status table, and the health endpoints to monitor.

Open OpenAPI JSONDownload OpenAPI JSON

Request IDs

Record X-Request-Id when a response supplies it. Kalinklo can preserve a valid supplied request ID or generate one; do not assume every ID is a UUID. X-Correlation-Id echoing is not part of this documented contract. Keep credentials and personal data out of IDs and logs.

Error responses

Organization API errors and public artist API errors use success: false with error.code and a human-readable error.message. Some errors add error.details. Branch on the code, not the message. This is not a universal shape for every route: health checks use data.status, and calendar or script routes have their own content types.

Example: a key lacks the required scope

json
{
  "success": false,
  "error": {
    "code": "API_SCOPE_MISSING",
    "message": "This API key is missing the required scope 'org:read:operations'."
  }
}

Read the status in context

StatusNext step
400 / 422Correct the request or field values before retrying.
401 / 403Check credentials and the required scope or permission.
402Review the workspace entitlement requirement; the response does not mean a payment was taken.
404The resource may be absent or hidden. Do not infer another workspace or private profile exists.
409Reload the current state and resolve the conflict before proceeding.
429Respect Retry-After when supplied; reduce request frequency.
500 / 502 / 503 / 504Retry safe reads with bounded backoff. Before repeating a write, inspect its resulting state.

Health is a limited signal

Use /api/health/live for process responsiveness and /api/health/ready or /api/health for readiness status. Anonymous callers see only data.status; internal diagnostics require operations authorization. A green health result is not evidence of a successful business workflow or provider transaction.

Report an integration problem

Include the method, path without secrets, approximate UTC time, HTTP status and request ID if available. Describe the expected and actual result. Do not send bearer keys, signing secrets, private payloads or customer records. See the authentication guide before adding retries.

Telemetry and Status · Developer Docs | Kalinklo