Errors and limits

Error format

Every error returns JSON with a text error field:

{ "error": "RUC no encontrado" }

The message text is for humans; in your code, decide by the HTTP status code.

Codes

Code	Meaning	What to do
400	The RUC is not 11 digits or not numeric.	Validate the value before calling.
401	The key is missing, wrong or revoked.	Check the Authorization: Bearer sk_… header and that the key is still active.
404	The RUC is not in the registry.	Confirm the number; do not retry unchanged.
429	Per-minute limit or quota exhausted.	Wait the Retry-After seconds and retry.
500	Internal error.	Retry with growing backoff.
503	The registry is briefly unavailable.	Retry with growing backoff.

What consumes credits

One credit is one GET /ruc/{id} lookup.

• 200 and 404 responses consume 1 credit.
• 400, 401, 429 and 5xx errors consume no credits.

Per-minute limit

Each API key can make up to 240 requests per minute. If you exceed it, the API returns 429 with {"error": "demasiadas solicitudes"} and a Retry-After header with the seconds until you can call again. A 429 consumes no credits.

Plan quota

• Free: when its cycle credits run out, the API returns 429 until the next cycle starts. It has no overage.
• Paid plans: if you go over the included credits, extra lookups are billed as overage and the API keeps responding. See the values in pricing.

Retry-After also gives the seconds until the next cycle when the 429 is a quota one.

Good practices

• Retry only 429, 500 and 503, with growing backoff.
• Do not retry 400, 401 or 404: the result will not change.
• Cache the result of a RUC you query often instead of asking every time.