Estado y soporte

Diagnostica antes de escalar

Casi todos los fallos reportados son una de cinco cosas, y cada una tiene una firma distinguible:

Síntoma	Causa probable	Dónde buscar
`401 unauthorized` en una llamada que ayer funcionaba	Clave rotada, deshabilitada, o falta el encabezado en una de las rutas de código	Autenticación
`402 insufficient_balance`	Saldo por debajo de la reserva para este envío	Cuenta y saldo
Una sola solicitud devuelve `200` pero no se cobró nada	Falló la combinación entera; el estado HTTP no es el resultado	Facturación y reembolsos
La misma solicitud tiene éxito y falla de forma alterna	Limitación de tasa, o una `Idempotency-Key` reutilizada con cargas útiles distintas	Límites de tasa, Idempotencia
Una tarea masiva se queda en `processing` y `last_progress_at` deja de avanzar	Una tarea realmente atascada, no una lenta	Estado de tarea

Vale la pena decir el caso de last_progress_at sin rodeos: el tiempo transcurrido no es la señal de fallo, una marca de tiempo detenida sí lo es. Una tarea de 500,000 filas puede ejecutarse legítimamente durante un buen rato. Una tarea cuyo last_progress_at no se ha movido es una tarea que escalar.

Qué incluir en una solicitud de soporte

Todos los campos siguientes los devuelve la API, lo que significa que incluirlos no te cuesta nada y ahorra una ida y vuelta:

Incluir	De dónde viene
`request_id`	Toda respuesta en tiempo real, incluidos los fallos que devolvieron un cuerpo
`task_id`	Todo envío masivo y toda respuesta de estado de tarea
`api_key_id`	`GET /v1/api-key` — identifica la clave sin exponerla
El estado HTTP exacto y el cuerpo de la respuesta	Tus propios registros; en particular, el campo `code`
Una marca de tiempo UTC con segundos	Tus propios registros
La solicitud que enviaste, con la clave redactada	Tu propio código

Nunca pegues una clave API en una solicitud de soporte. api_key_id identifica la clave, y la clave en sí da acceso a tu saldo.

Comunicación de incidentes

Los avisos a nivel de cuenta — mantenimiento programado, capacidad degradada — aparecen en la Consola, que es también donde viven el saldo y los registros. La API expone esas mismas condiciones directamente a tu integración, como códigos de error en lugar de texto:

Código	Qué significa para una integración en ejecución
`detection_capacity_unavailable`	No hay capacidad en este momento. Aplica retroceso y reintenta; no se cobró nada.
`realtime_route_unavailable`	No hay ninguna ruta en tiempo real disponible. Aplica retroceso y reintenta.
`realtime_rate_limiter_unavailable`	El propio limitador está caído, así que no se puede decidir la admisión. Reintenta más tarde.
`realtime_fact_cache_unavailable`	Una dependencia en tiempo real está caída. Reintenta más tarde.

Todos son 503 y todos están en el grupo de «esperar y reintentar» — consulta Códigos de error para ver la agrupación completa, incluidos los fallos que es seguro reintentar con la misma Idempotency-Key.

Dónde está la plataforma hoy

Dos hechos operativos son verificables desde fuera y conviene conocerlos antes de abrir un incidente:

La API se sirve detrás de Cloudflare, así que la ruta de red y la terminación TLS las opera Cloudflare y no un único host de origen.
Toda respuesta lleva X-RateLimit-Remaining, así que un cliente que registra los encabezados de respuesta puede distinguir «limitado por mi propio límite» de «el servicio está caído» sin preguntar a nadie. Los grupos general y de detección también llevan X-RateLimit-Limit en todas las respuestas; el de tiempo real no, porque consume un depósito de tokens en lugar de un techo fijo por minuto.

Códigos de error — los grupos de reintento, que es la tabla de triaje más rápida
Seguridad — manejo de claves, rotación de una clave y qué no enviar nunca