Errores y límites

Formato de los errores

Todos los errores devuelven un JSON con un campo error en texto:

{ "error": "RUC no encontrado" }

El texto del mensaje es para personas; en tu código decide con el código de estado HTTP.

Códigos

Código	Significado	Qué hacer
400	El RUC no tiene 11 dígitos o no es numérico.	Valida el dato antes de consultar.
401	Falta la key, es incorrecta o fue revocada.	Revisa la cabecera Authorization: Bearer sk_… y que la key siga activa.
404	El RUC no existe en el padrón.	Confirma el número; no reintentes igual.
429	Límite por minuto o cuota agotada.	Espera lo que indica Retry-After (en segundos) y reintenta.
500	Error interno.	Reintenta con espera creciente; si persiste, vuelve a intentarlo más tarde.
503	El padrón no está disponible por un momento.	Reintenta con espera creciente.

Qué consume créditos

Un crédito equivale a una consulta de GET /ruc/{id}.

• Consumen 1 crédito las respuestas 200 y 404.
• No consumen créditos 400, 401, 429 ni los errores 5xx.

Límite por minuto

Cada API key puede hacer hasta 240 solicitudes por minuto. Si lo superas, la API responde 429 con {"error": "demasiadas solicitudes"} y la cabecera Retry-After con los segundos hasta que puedas volver a consultar. Un 429 no consume créditos.

Cuota del plan

• Free: cuando se agotan sus créditos del ciclo, la API responde 429 hasta que empiece el siguiente ciclo. No tiene excedente.
• Planes de pago: si superas los créditos incluidos, las consultas adicionales se cobran como excedente y la API sigue respondiendo. Mira los valores en precios.

Retry-After también indica los segundos hasta el próximo ciclo cuando el 429 viene por cuota.

Buenas prácticas

• Reintenta solo 429, 500 y 503, con espera creciente.
• No reintentes 400, 401 ni 404: el resultado no va a cambiar.
• Guarda en tu sistema el resultado de un RUC que consultes seguido, en vez de pedirlo cada vez.