Errores y límites de peticiones
Formato de error de AdLib, códigos de error, límites de peticiones por minuto según el plan, cabeceras de límite y cómo reintentar.
Formato de error
Los errores devuelven un cuerpo JSON con un código pensado para máquinas:
{
"error": {
"code": "not_found",
"message": "ad meta:123 not found",
"request_id": "c821fd4d-699b-4080-9776-841f4b57aad2",
"billed": false
}
}Los errores nunca se facturan. Si nos escribes, incluye el request_id (también viene en la cabecera X-Request-Id).
Códigos
| Código | Significado | Qué hacer |
|---|---|---|
bad_request |
Falta un parámetro o no es válido; details dice cuál |
Corrige la petición |
invalid_cursor |
El cursor no viene de un next_cursor |
Devuelve next_cursor tal cual |
invalid_webhook_url |
La URL del webhook no es una dirección http(s) pública (se rechazan localhost, las redes privadas, link-local y los hosts internos) | Usa una URL accesible desde internet |
interval_too_short |
interval_hours está por debajo de lo que permite tu cuenta (24 con los créditos gratis, 6 cuando hayas comprado un pack) |
Sube interval_hours o compra un pack |
watchlist_too_large |
Las listas de seguimiento seguirían más marcas de las que permite tu cuenta (3 con los créditos gratis, 250 tras comprar un pack) | Quita marcas o compra un pack |
batch_too_large |
El lote tiene más elementos de los que permite tu cuenta (10 con los créditos gratis, 100 tras comprar un pack) | Divide el lote |
unauthorized |
Falta la clave de API o no es válida | Revisa la cabecera X-API-Key |
account_blocked |
La cuenta está bloqueada | Escríbenos |
history_limit |
El anuncio es más antiguo de lo que cubre el archivo de tu cuenta (12 meses con los créditos gratis) | Compra un pack para acceder al archivo completo |
not_found |
El anuncio, el anunciante, el trabajo o el endpoint no existe | Revisa el id o la ruta |
rate_limited |
Has superado las peticiones por minuto de tu cuenta (30 con los créditos gratis, 300 tras comprar un pack) | Espera los segundos que indique Retry-After |
quota_exceeded |
Se han agotado los créditos gratis y los packs | Compra un pack; no reintentes |
upstream_error |
La biblioteca de la plataforma ha fallado o ha bloqueado la petición | Reintenta más tarde; consulta el estado |
internal_error |
El fallo es nuestro | Reintenta; avísanos si se repite |
Límites de peticiones
| Cuenta | Peticiones por minuto |
|---|---|
| Con los créditos gratuitos | 30 |
| Tras el primer pack de créditos | 300 |
Cada respuesta lleva X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset (segundos hasta que se reinicia la ventana). Si superas el límite, la API responde 429 rate_limited con una cabecera Retry-After.
Reintentos
Reintenta rate_limited, upstream_error e internal_error con backoff. No reintentes bad_request, unauthorized, not_found ni quota_exceeded. A veces las plataformas cambian sus bibliotecas sin avisar; cuando una se rompe, sus llamadas fallan rápido, no se facturan y aparecen en la página de estado.