Resuelve errores 400, 401, 403, 404, 409 y 429 de la API

Guarda el estado HTTP, el cuerpo de error y el encabezado x-request-id. Ese identificador permite correlacionar la solicitud sin compartir tu clave.

401 Unauthorized

Falta la cabecera Authorization, el formato es inválido o la clave fue revocada. Usa Bearer, seguido de un espacio y la clave completa que empieza por syn_. El prefijo visible en el panel no es la clave completa.

Verifica con GET /api/v1/_meta. Si perdiste la clave, crea otra y actualiza tu servidor; no se puede volver a consultar el secreto original.

403 Forbidden

Una clave de solo lectura no puede crear contactos. Genera una clave con alcance write para POST /api/v1/contacts. Las rutas de administración del panel usan sesión de usuario y no son sustitutos de la API pública.

400 Invalid request

Comprueba parámetros obligatorios y los tipos enviados. GET /api/v1/messages requiere conversation_id. POST /api/v1/contacts requiere phone como texto de al menos cinco caracteres. Usa Content-Type: application/json para enviar JSON.

404 Not found

El recurso no existe o no pertenece a la cuenta de la clave. Las conversaciones eliminadas tampoco se consultan desde las rutas de conversaciones. Verifica el identificador con una consulta de listado de la misma cuenta.

409 Conflict

Al crear un contacto, el teléfono ya puede existir. Consulta los contactos antes de repetir el POST. Un reintento automático de una escritura puede duplicar una operación si no verificas el resultado anterior.

429 Rate limited

Respeta el encabezado retry-after, expresado en segundos. Reduce la concurrencia y evita consultar en bucles sin espera. Usa paginación y, cuando corresponda, eventos por webhook.

500 Internal

Conserva x-request-id, hora y ruta. Para lecturas, aplica reintentos limitados con espera. Para escrituras, verifica si el registro llegó a crearse antes de repetir.

Formato: los errores devuelven un objeto error con code y message. request_id puede aparecer en el cuerpo; para correlación usa el encabezado x-request-id cuando esté disponible.