Primeros pasos

# Errores

Códigos de estado HTTP que devuelve el API, qué significan y cómo manejarlos.

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.