Failed requests return a 4xx or 5xx status and a JSON error object.
link The error body
400 Bad Request
{
"success": false,
"data": null,
"error": {
"code": "VALIDATION_ERROR",
"field": "reference",
"message": "reference is required (1 to 200 characters)."
},
"meta": {
"request_id": "7488379f-f816-46fc-985f-4274a7c4430f",
"timestamp": "2026-10-15T12:10:11.419698+00:00"
}
}error.code
string
A stable code. Branch on this, not on the message.
error.message
string
Human-readable description. It can change; don't parse it.
error.field
string
For validation errors, the request field at fault.
meta.request_id
string
Quote this if you contact us about a request.
link Codes
| Status | Code | Means |
|---|---|---|
400 | VALIDATION_ERROR | A field is missing or isn't valid. See field. |
401 | AUTHENTICATION_ERROR | No API key, a key that isn't valid or has been revoked, or a suspended account. |
403 | AUTHORIZATION_ERROR | The key is valid but can't do this: it lacks the scope for the call, or it's a publishable key on a website a button doesn't allow. |
404 | NOT_FOUND | No such session, or it belongs to another account. |
410 | SESSION_ENDED | The session has already ended, so it can't be changed. |
429 | RATE_LIMIT_ERROR | Too many requests. See Rate limits. |
5xx | INTERNAL_ERROR | Something went wrong on our side. Try again with a short delay. |
Retrying safely
Retry 429 and 5xx responses, waiting a little longer each time. Don't retry 4xx errors without changing the request: they'll fail the same way.