Errores

La API usa códigos de estado HTTP comunes. Todo cuerpo de error 4xx es JSON con un detail:

{ "detail": "api key lacks the leads:write scope" }

Los errores de validación de la solicitud (422) traen en cambio una lista, con una entrada por problema e indicando dónde está:

{
  "detail": [
    { "type": "missing", "loc": ["body", "person", "name"], "msg": "Field required", "input": {} }
  ]
}

Códigos de estado

• 200 OK / 201 Created / 202 Accepted / 204 No Content — éxito. La ingesta responde 201 para un Lead nuevo y 200 para uno que ya existía.
• 400 Bad Request — un header mal formado, por ejemplo un Idempotency-Key de más de 255 caracteres.
• 401 Unauthorized — no hay clave de API, o es desconocida, está vencida o fue revocada.
• 402 Payment Required — la suscripción está en solo lectura, así que se rechazan las escrituras. Las lecturas y la ingesta siguen funcionando.
• 403 Forbidden — a la clave le falta el permiso que necesita la operación.
• 404 Not Found — no hay nada con ese id en tu cuenta.
• 409 Conflict — una solicitud con el mismo Idempotency-Key todavía se está ejecutando; reintenta en un momento.
• 422 Unprocessable Content — la solicitud no es válida (falta un campo, un cursor incorrecto, una URL de webhook que no es https pública), o se reutilizó un Idempotency-Key para otra solicitud.
• 429 Too Many Requests — se agotó un límite de uso; espera Retry-After segundos.
• 500 Internal Server Error — es culpa nuestra; el cuerpo es texto plano. Reintenta con el mismo Idempotency-Key.
• 503 Service Unavailable — la cuenta está suspendida.

Qué reintentar

Reintenta los 429, 409, 500, 502, 503, 504 y los errores de red con backoff exponencial, y envía siempre un Idempotency-Key en los POST para que el reintento sea seguro. No reintentes otras respuestas 4xx sin cambiar la solicitud.

Las posibles respuestas de cada operación están en la referencia de la API.