Platform
Errors
Every error has the same shape, a stable machine-readable code and the request id.
{
"error": {
"type": "validation_error",
"code": "invalid_phone_number",
"message": "phone is not a valid phone number. Use E.164, e.g. +4917612345678.",
"param": "phone",
"request_id": "req_4KqV8ZtM1bN7cX2aP9sD"
}
}Types
| type | HTTP | What to do |
|---|---|---|
authentication_error | 401 | Check the key and its environment. |
permission_error | 403 | The key may not do this — scopes, archived project, production access. |
not_found | 404 | Wrong id, or it belongs to another project or environment. |
idempotency_error | 409 | The Idempotency-Key was already used for a different lead. |
validation_error | 422 | Fix the field named in param. Do not retry unchanged. |
rate_limit_error | 429 | Reserved. Not enforced during the preview. |
api_error | 500 | Retry with the same Idempotency-Key and exponential backoff. |
Codes
| HTTP | type | code |
|---|---|---|
| 401 | authentication_error | invalid_api_key, secret_key_required |
| 403 | permission_error | missing_scope, project_unavailable, production_not_enabled |
| 404 | not_found | lead_not_found, unknown_route |
| 409 | idempotency_error | idempotency_key_reused |
| 422 | validation_error | invalid_json, invalid_body, unsupported_method, missing_external_id, external_id_too_long, missing_contact, invalid_phone_number, invalid_email, invalid_postal_code |
| 500 | api_error | lead_not_created |
For each endpoint's errors and the retry strategy, see the Leads reference and Retry strategy.
Codes are stable within v1; new codes may be added. Messages are written for people and may change — branch on code, never on message.