Errors
Every error has the same shape and a stable code.
Errors use HTTP status codes and always return the same body:
{
"error": {
"type": "invalid_request_error",
"code": "validation_failed",
"message": "The email field must be a valid email address.",
"param": "email"
}
}typegroups errors:authentication_error,permission_error,invalid_request_error,rate_limit_errororapi_error.codeis stable and meant for your code. Branch on it, not onmessage.messageis for humans and may change.paramnames the related parameter, when there is one.- Validation errors (
422, codevalidation_failed) also includeerrorswith every invalid field.
Common codes
| Status | Code | Meaning |
|---|---|---|
| 401 | invalid_token | Missing, unknown, expired or revoked token, or the owner left the company |
| 403 | insufficient_scope | The token lacks the scope for this endpoint |
| 403 | permission_denied | The token's owner lacks the permission |
| 403 | package_required | The company is not on the Automate package |
| 403 | ip_not_allowed | The request came from an IP address outside the allowlist |
| 404 | resource_missing | The object does not exist or is outside the token's reach |
| 409 | request_in_progress | A request with the same Idempotency-Key is still running |
| 422 | validation_failed | The request is invalid; see param and errors |
| 409 | duplicate_external_reference | A recipient with this external_reference already exists |
| 422 | no_trees_available | Not enough unassigned trees to assign to a recipient or reserve for a gift code |
| 422 | gift_code_claimed | The gift code was already claimed and cannot be revoked |
| 422 | idempotency_key_reused | The Idempotency-Key was used for a different request |
| 429 | rate_limited | Too many requests; wait Retry-After seconds |