Errores, límites y buenas prácticas

Formato de los errores

Todo error vuelve así:

{
  "error": "validation_failed",
  "message": "Algún campo es incorrecto. `details` dice cuál y por qué.",
  "details": { "name": ["Required"] },
  "request_id": "01a3c0de-7a11-7b22-8c33-9d44e55f6677"
}

error es el código estable: su sistema decide qué hacer a partir de él.
message explica, en el idioma del encabezado Accept-Language (portugués, inglés o español; inglés por omisión).
request_id identifica la llamada: cítelo al hablar con soporte. Puede enviar el suyo en X-Request-Id.

HTTP	Código	Qué hacer
401	`unauthorized`	Falta la clave. Envíe Authorization: Bearer <clave>.
401	`api_key_invalid`	Clave inválida o revocada. Revísela o cree otra en Configuración › API.
401	`api_key_expired`	La clave venció. Cree otra en Configuración › API.
403	`api_key_address_not_allowed`	Esta clave no acepta llamadas desde esta dirección IP. Agregue la dirección a la clave.
403	`insufficient_scope`	La clave no tiene el alcance de esta llamada. `details.required` indica cuáles sirven.
403	`not_available_to_api_keys`	Esta llamada no forma parte de la API pública.
403	`not_available_to_test_keys`	Esta llamada no tiene modo de prueba: use una clave de producción.
403	`permission_denied`	La clave no puede hacer esto.
403	`integration_template_only`	Texto y archivos piden el alcance messages:send_text; sin él, solo plantillas aprobadas.
404	`not_found`	No encontrado.
404	`campaign_not_found`	Campaña no encontrada en esta empresa.
404	`contact_not_found`	Contacto no encontrado en esta empresa.
422	`validation_failed`	Algún campo es incorrecto. `details` dice cuál y por qué.
409	`campaign_not_editable`	La campaña ya no es borrador; solo un borrador se puede editar o enviar.
409	`template_not_approved`	Meta aún no aprobó la plantilla. Espere la aprobación o elija otra.
409	`campaign_audience_empty`	Nadie del público puede recibir la campaña. Vea los motivos en la vista previa.
409	`contact_exists`	Ya existe un contacto con este teléfono. `details.contactId` dice cuál.
409	`window_closed`	La ventana de 24 horas está cerrada: solo una plantilla aprobada puede iniciar la conversación.
409	`idempotency_key_reused`	Esta Idempotency-Key ya se usó con otra solicitud. Use una clave nueva por solicitud.
409	`idempotency_in_progress`	La primera solicitud con esta Idempotency-Key aún está en curso. Reintente en un momento.
429	`rate_limited`	Límite de 600 llamadas por minuto. Espere los segundos de Retry-After.
500	`internal_error`	Error de nuestro lado. Ya fuimos avisados; reintente y cite el request_id si persiste.

Límite de llamadas

Cada clave puede hacer 600 llamadas por minuto. Toda respuesta dice dónde está:

RateLimit-Limit: 600
RateLimit-Remaining: 587
RateLimit-Reset: 41

Pasado el límite, la respuesta es 429 rate_limited con Retry-After (segundos). Espere ese tiempo y reintente. El envío de una campaña no cuenta: quien envía es DoneTalk, al ritmo que Meta permite para el número.

Reintentar sin duplicar

Envíe Idempotency-Key (hasta 200 letras, números, _ . : -) en creaciones y envíos. Si la red falla y envía la misma llamada otra vez con la misma clave dentro de 24 horas, recibe la primera respuesta, con Idempotent-Replayed: true, y nada se hace dos veces. La misma clave con otra solicitud devuelve 409 idempotency_key_reused.

Idempotency-Key: pedido-88213-campana

Paginación

Campañas: limit y cursor; la respuesta trae nextCursor (null en la última página).
Contactos: limit y before (el lastActivityAt del último de la página).
Destinatarios de una campaña: limit y offset, o format=csv para todo.

Versiones

La v1 solo gana cosas nuevas: más campos y llamadas, nunca un cambio en lo que existe. Ignore los campos que no conoce. Si algún día algo debe cambiar, nace la v2 y la v1 sigue funcionando por 12 meses, con aviso.

Esta página en Markdown