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.
| Status Code | Meaning | Description |
|---|---|---|
| 200 | OK | Request succeeded |
| 400 | Bad Request | Invalid query parameter or missing required configuration |
| 401 | Unauthorized | X-API-Key header is missing or invalid |
| 404 | Not Found | The requested resource does not exist |
Error Response Body
When an error occurs, the API returns the following JSON body:Response Fields
| Field | Type | Description |
|---|---|---|
ok | boolean | false on error |
error | string | Human-readable error message |
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.