El API usa códigos de estado HTTP estándar. El cuerpo de la respuesta, cuando lo hay, contiene un campo message en español y un código de error apto para manejo programático.
| Estado | Significado |
|---|---|
200 OK |
Validación completada. valid: false combinado con un mensaje transitorio del SAT significa "reintenta más tarde." |
202 Accepted |
Validación asíncrona iniciada. Se devuelve cuando se envía webhook_url. El resultado completo se envía vía POST a tu URL de webhook cuando está listo. |
401 Unauthorized |
Llave API faltante o inválida. |
402 Payment Required |
Créditos insuficientes y sin saldo prepagado. Agrega saldo o mejora el plan. |
422 Unprocessable Entity |
La solicitud estaba bien formada pero la entrada es inválida. El campo error es uno de: missing_rfc, invalid_rfc, invalid_webhook_url, missing_curp, invalid_curp, invalid_fields. |
429 Too Many Requests |
Límite de tasa excedido. Espera y reintenta. |
500 Internal Server Error |
Algo salió mal de nuestro lado. Por favor reintenta. |
504 Gateway Timeout |
La consulta no terminó en 90 segundos. El cuerpo es {"error": "request_timeout"} y la solicitud no se cobra. |
Manejo de resultados "desconocidos"
Un 200 OK con valid: null significa que se llegó a nuestro sistema pero no pudimos contactar al SAT. Trátalo como transitorio y reintenta, normalmente en cuestión de segundos. El mensaje correspondiente está en español y describe la condición del lado del SAT.
Las consultas de CURP, INE y CFDI siguen la misma regla: found: null significa que no se pudo contactar a RENAPO, al INE o al portal de CFDI del SAT. Reintenta más tarde; estas respuestas no se cobran.
Timeouts del cliente
Una consulta puede tardar hasta 90 segundos porque espera a un sitio de gobierno. Si tu cliente HTTP cierra la conexión antes, cancelamos la consulta, no recibes respuesta y la solicitud no se cobra. Es un timeout de tu lado, no una caída: configura el timeout de tu cliente en al menos 90 segundos, o envía webhook_url en los endpoints que lo aceptan para recibir el resultado por webhook.