Errors & retries
Know when to fix the request and when to try again.
Read the response
{
"detail": "external_id is required"
}Most errors use a detail string. Schema validation errors may return an array of field-level details. Check the HTTP status before reading a success response.
| Status | Action |
|---|---|
| 400 · Bad request | Check required values, event type and conversation_id |
| 401 · Unauthorised | Check the credential; it may be missing, invalid or revoked |
| 403 · Forbidden | Check plan availability and workspace permissions |
| 404 · Not found | Check the resource belongs to this workspace |
| 409 · Conflict | The same external_id may still be processing; retry shortly |
| 413 · Too large | Reduce the message or metadata size |
| 422 · Validation error | Use field-level detail to correct the JSON schema |
| 429 · Too many requests | Back off; honour Retry-After when provided |
| 503 · Unavailable | Retry transient failures with backoff |
Retry without duplicates
Use exponential backoff with jitter for temporary failures. Reuse the original external_id for the same logical event. A successful duplicate response means the original resource already exists; do not create a new ID just to retry.