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

typeHTTPWhat to do
authentication_error401Check the key and its environment.
permission_error403The key may not do this — scopes, archived project, production access.
not_found404Wrong id, or it belongs to another project or environment.
idempotency_error409The Idempotency-Key was already used for a different lead.
validation_error422Fix the field named in param. Do not retry unchanged.
rate_limit_error429Reserved. Not enforced during the preview.
api_error500Retry with the same Idempotency-Key and exponential backoff.

Codes

HTTPtypecode
401authentication_errorinvalid_api_key, secret_key_required
403permission_errormissing_scope, project_unavailable, production_not_enabled
404not_foundlead_not_found, unknown_route
409idempotency_erroridempotency_key_reused
422validation_errorinvalid_json, invalid_body, unsupported_method, missing_external_id, external_id_too_long, missing_contact, invalid_phone_number, invalid_email, invalid_postal_code
500api_errorlead_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.