Standard API Error Envelope
Application-level handlers return errors in this shape:Authentication Errors
The auth layer behaves like this:
Route handlers can also return
403 when you try to access a case owned by another user.
Validation And Conflict Errors
429 Cases
There are two different ways to get throttled:
Usage Limit 429
POST /cases returns:
- status
429 - code
USAGE_LIMIT_REACHED
Gateway Throttling 429
API Gateway also has route throttling configured:
POST /caseshas a tighter limit than other routes- defaults vary by environment
429 responses may not use the standard JSON envelope.
500 Cases
Known handler behavior:
POST /casesreturnsINTERNAL_ERRORwhen persistence or queueing failsPOST /cases/{id}/inputreturnsINTERNAL_ERRORwhen queueing the input failsGET /cases/{id}/attachments/{attachmentId}returnsINTERNAL_ERRORwhen AgentMail attachment lookup fails
Transcript Fetch Caveat
GET /cases/{id} does not wrap transcript-fetch failures in a local try/catch.
If includeTranscript=true and the AgentMail thread fetch fails, the platform may return a generic 500 instead of the standard JSON error shape.
Webhook Failure Handling
Webhook delivery is best-effort:- one HTTP request
- no signature
- no retry
- failure only logged server-side
FAQ / Edge Cases
Does POST /cases support idempotency?
No. Sending the same request twice creates two cases.
Does 202 Accepted on POST /cases/{id}/input mean the case has resumed?
No. It only means the input was queued successfully.
Why is nextActionAt a huge number?
The code uses 253402300799999 as an “unscheduled” sentinel instead of null.
Is resultStatus a closed enum?
No. Known values exist, but the implementation types it as string and currently mixes lowercase workflow values with uppercase provider-delivery values.