HTTP Status Codes
The API uses standard HTTP status codes. Because the AI Helpdesk API is read-only, only200 is used in the 2xx range.
Error Response Body
When an error occurs, the API returns the following JSON body:Response Fields
Common Errors
Authentication Error (401)
X-API-Key header is missing or contains an invalid value.
Resource Not Found (404)
sessionKey, docId, typePath, integrationId, …) does not exist or belongs to a different tenant.
Invalid Parameters (400)
status or assigneeType is out of range, or limit is outside the allowed range (1..100, or 1..500 for procedures).
Best Practices
- Always branch on the
okfield — do not infer success purely from HTTP code. - Log the
errormessage and translate it into a user-facing message as appropriate. - Do not auto-retry 401 — it requires a key rotation. Surface it to operators.
- Do not auto-retry 404 — the caller logic is at fault.
- Avoid logging sensitive information such as full API keys.