Docs

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:

JSON
{
  "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.