Errores y límites

Los formatos de error, cada código de estado y su causa, los códigos de fallo del negocio, y cómo gestionar los límites de solicitudes y los reintentos.

Insertar

<a href="https://numestri.com/docs/es/errors"><img src="https://numestri.com/docs/_api/public/orgs/25229885-9620-4c08-bd2e-a0d0d74ac8b6/spaces/ef21e0c3-966d-4b03-b6d2-e66d449835d4/pages/12ccbdc6-a0f4-4fe1-9e78-7f32f70524c8/social-card.svg?v=3e7ae33eec8b" alt="Errores y límites" width="600" height="315"></a>

Una solicitud fallida siempre lleva success: 0. Hay dos formatos principales, según lo que haya salido mal, y los distingues porque el cuerpo tenga o no un arreglo errors.

La solicitud en sí era incorrecta

Los problemas de la solicitud (un parámetro que falta o no es válido, la clave de API, el límite de solicitudes, un nivel del catálogo sin nada debajo) devuelven un arreglo errors:

{
  "success": 0,
  "errors": [{
    "message": "You are missing a required parameter for this request.",
    "param": "country",
    "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
  }]
}

Campo	Siempre presente	Significado
`message`	sí	Qué salió mal, en inglés sencillo.
`param`	no	El parámetro con el problema (`key` para los problemas con la clave de API).
`description`	no	Qué debe contener ese parámetro, o cómo superar el error.

Corrige la solicitud; si la reintentas sin cambios, fallará igual (salvo 429 y 503, más abajo).

Códigos de estado

HTTP	Cuándo	`message` de ejemplo
`304`	Un nivel del catálogo para el que enviaste `If-None-Match` no cambió. Sin cuerpo: reutiliza lo que tienes. Consulta la caché.	—
`400`	Falta un parámetro obligatorio.	`You are missing a required parameter for this request.`
`400`	Se llamó sin clave a un endpoint que la necesita (`param: "key"`).	`You are missing a required parameter for this request.`
`400`	Un id no es exacto: el nombre de una plataforma en lugar de su id, `us` en lugar de `US`.	`No platform has the id "Telegram". See /api/v1/catalog/platforms.`
`400`	Un parámetro tiene un formato incorrecto.	`max_price must be a positive amount in dollars, e.g. 0.75.`
`403`	La clave de API no existe o fue revocada, en cualquier endpoint, también en los públicos (`param: "key"`).	`Invalid API key`
`404`	Un nivel del catálogo no tiene stock para la plataforma, el país o el proveedor de la ruta. El mensaje te remite al nivel superior.	`Nothing is in stock for the platform "telegarm". See /api/v1/catalog/platforms.`
`404`	`/rental/retrieve_pricing` no tiene alquileres para ese país (o para esa plataforma allí).	`No rentals are available in "XX". Check /api/v1/rental/retrieve_all for the current list.`
`409`	Todavía se está procesando una compra con el mismo `Idempotency-Key`.	`A purchase with this Idempotency-Key is still in progress. Retry in a few seconds.`
`422`	Se reutilizó un `Idempotency-Key` para otro tipo de solicitud.	`This Idempotency-Key was already used for a different request. Use a new key.`
`429`	Demasiadas solicitudes sin clave desde tu dirección IP.	`Rate limit exceeded. Slow down and try again.`
`429`	Demasiadas solicitudes con tu clave.	`Rate limit exceeded. Slow down and try again.`
`429`	Demasiadas solicitudes con una clave no válida desde tu dirección IP (`param: "key"`).	`Too many requests with an invalid API key. Wait before trying again.`
`500`	Algo salió mal por nuestra parte.	`Could not load the catalogue.`
`503`	El catálogo todavía está cargando los precios, normalmente justo después de un reinicio. Vuelve a intentarlo en unos segundos.	`Prices are being refreshed. Try again in a few seconds.`

Fíjate en la diferencia entre 400 y 404 para los ids: un endpoint que recibe service y country como parámetros (/request/price, /purchase/sms) responde a un id desconocido con 400; una ruta del catálogo (/catalog/platforms/{platform}/…) responde con 404, porque el árbol solo muestra lo que tiene stock y ese nivel está vacío.

La solicitud era correcta, pero no se puede completar

Pedir números, alquilarlos y comprar cuentas de correo fallan de las mismas pocas maneras, y siempre incluyen dos campos según los cuales actuar:

type: la categoría general que la mayoría de los clientes de verificación ya gestionan.
code: el motivo exacto.

{
  "success": 0,
  "message": "That option is no longer available. Pick another.",
  "type": "OUT_OF_STOCK",
  "code": "OPTION_GONE"
}

`code`	`type`	HTTP	Qué hacer
`OUT_OF_STOCK`	`OUT_OF_STOCK`	409	Prueba otro país u otra opción, o inténtalo más tarde.
`OPTION_GONE`	`OUT_OF_STOCK`	409	La `option` que enviaste ya no existe. Vuelve a consultar las opciones y elige de nuevo.
`PROVIDER_UNAVAILABLE`	`OUT_OF_STOCK`	409	El `provider` que enviaste no tiene stock aquí. Elige otro o quita `provider`.
`INSUFFICIENT_BALANCE`	`BALANCE_ERROR`	402	Recarga saldo. El mensaje indica cuánto cuesta el pedido y cuál es tu saldo.
`PRICE_ABOVE_MAX`	`PRICE_NOT_FOUND`	400	El precio supera tu `max_price`. El mensaje indica cuál es el precio.
`INVALID_DAYS`	`PRICE_NOT_FOUND`	400	Ese plazo de alquiler no se ofrece. Usa uno de `retrieve_pricing`.
`NOT_SOLD`	`PRICE_NOT_FOUND`	409	Esa plataforma no se vende en ese país en este momento.
`UNAVAILABLE`	`SERVICE_UNAVAILABLE`	503	El suministro no está disponible momentáneamente. Reintenta tras una breve espera.
`UNSUPPORTED`	`UNSUPPORTED`	400 / 409	No disponible para este producto, número o acción.
`RATE_LIMITED`	`RATE_LIMITED`	429	Demasiadas compras en tu cuenta (60 por minuto de forma predeterminada), o el suministro está limitando las solicitudes momentáneamente. Espera los segundos de `Retry-After` cuando se envíe.
`NOT_FOUND`	`NOT_FOUND`	404	No existe ese pedido, alquiler o cuenta en tu cuenta.
`CANCEL_TOO_EARLY`	`CANCEL_TOO_EARLY`	409	Solo en `/sms/cancel`. Espera `retry_after` segundos y vuelve a cancelar.
`INVALID_QUANTITY`	`INVALID_QUANTITY`	400	Cuentas de correo: elige entre 1 y 500.
`UNKNOWN_PRODUCT`	`UNKNOWN_PRODUCT`	400	Cuentas de correo: ese producto no existe.
`UNKNOWN`	`UNKNOWN`	500	Algo salió mal por nuestra parte. Reintenta una vez; si persiste, consulta la página de estado.

Una cotización sin nada en stock sigue la misma idea, sin code: /request/price responde 409 con type: "OUT_OF_STOCK" y las options (agotadas).

Algunas respuestas de gestión de pedidos solo llevan un message; por ejemplo, /sms/check sobre un pedido que no es tuyo:

{ "success": 0, "message": "We could not find this order!" }

Un pedido rechazado no cuesta nada

Cualquier fallo antes de que se entregue un número o una cuenta deja tu saldo intacto. Si un pedido no se puede completar después de haber reservado tu saldo, el dinero vuelve de inmediato, antes de que llegue la respuesta.

Límites de solicitudes

Quién llama	Límite (predeterminado)	Se cuenta por
Sin clave, endpoints públicos	10 solicitudes por segundo	Dirección IP
Con clave	32 solicitudes por segundo	Cuenta
Compras de cualquier tipo	60 por minuto	Cuenta

Los rechazos por límite llevan una cabecera Retry-After: espera esa cantidad de segundos antes de reintentar. Un rechazo por exceso de solicitudes se ve así:

{ "success": 0, "errors": [{ "message": "Rate limit exceeded. Slow down and try again." }] }

Sin clave, el error también incluye una description que te sugiere enviar tu clave, lo que te pasa al límite más alto de tu cuenta. El límite de compras responde con el formato de negocio, con code: "RATE_LIMITED". Más detalles en Autenticación.

Reintentar de forma segura

Reintenta los 429 y 503 tras una espera breve y creciente, respetando Retry-After cuando esté presente. No reintentes otros 4xx sin cambios.
Una solicitud de pedido que agota el tiempo de espera por tu lado puede haberse completado igualmente. Envía una cabecera Idempotency-Key con cada compra y reintenta con la misma clave: una repetición después de un éxito devuelve el pedido original (marcado con Idempotent-Replayed: true) y no cobra nada. Sin ella, consulta /request/active antes de volver a pedir, o podrías comprar dos números.

Actualizado 16 oct 2026

¿Te resultó útil esta página?