Get Started

Errors

Every HTTP status code the API returns, what each one means, and how to handle validation errors, timeouts, and a registry that cannot be reached.

The API uses standard HTTP status codes. The response body, when present, contains a Spanish-language message field and an error code suitable for programmatic handling.

Status Meaning
200 OK Validation completed. valid: false combined with a transient SAT message means "retry later."
202 Accepted Async validation started. Returned when webhook_url is provided. The full result is POSTed to your webhook URL when ready.
401 Unauthorized Missing or invalid API key.
402 Payment Required Insufficient credits and no prepaid balance. Add balance or upgrade the plan.
422 Unprocessable Entity The request was well-formed but the input is invalid. The error field is one of: missing_rfc, invalid_rfc, invalid_webhook_url, missing_curp, invalid_curp, invalid_fields.
429 Too Many Requests Rate limit exceeded. Back off and retry.
500 Internal Server Error Something went wrong on our end. Please retry.
504 Gateway Timeout The lookup did not finish within 90 seconds. The body is {"error": "request_timeout"} and the request is not charged.

Handling "unknown" results

A 200 OK with valid: null means we reached our system but SAT could not be reached. Treat this as transient and retry, usually within seconds. The corresponding message is in Spanish and describes the SAT-side condition.

CURP, INE, CFDI, and constancia lookups follow the same rule: found: null means RENAPO, INE, or SAT's CFDI portal or QR validator could not be reached. Retry later; these answers are not charged.

Client timeouts

A lookup can take up to 90 seconds because it waits on a government site. If your HTTP client closes the connection first, we cancel the lookup, you receive no answer, and the request is not charged. This is a timeout on your side, not an outage: set your client timeout to at least 90 seconds, or send webhook_url on the endpoints that accept it to get the result by webhook.