Errores

Todos los fallos tienen la misma estructura y un code estable. Decide en función del código: el mensaje está escrito para personas y puede cambiar de redacción.

{ "error": { "code": "invalid_key", "message": "That API key does not exist." } }

Algunos errores incluyen campos adicionales junto a esos dos: parameter con el parámetro incorrecto, retry_after con el tiempo de espera, limit y used cuando se ha agotado una cuota.

Todos los códigos

Estado	Código	Cuándo
400	`missing_query`	`query` estaba vacío o no se envió.
400	`unknown_format`	`format` no es ninguno de los seis.
400	`unknown_column`	`columns` menciona un campo que no existe.
400	`format_not_available`	Se pidió un formato plano donde lo que se devuelve no son filas.
400	`per_page_too_large`	`per_page` supera el límite de filas de tu plan. El límite aparece en el error.
400	`invalid_json`	El cuerpo del POST no es un JSON válido.
401	`missing_key`	Falta el encabezado `Authorization: Bearer`.
401	`invalid_key`	La clave no corresponde a ninguna cuenta.
403	`plan_required`	La cuenta no tiene un plan de pago.
404	`unknown_endpoint`	La ruta no existe. Las rutas conocidas se enumeran en el error.
405	`method_not_allowed`	La API es de solo lectura. Usa GET, o POST con un cuerpo JSON.
429	`too_many_requests`	Llegan más de diez solicitudes por minuto (API y MCP en conjunto).
429	`quota_exceeded`	Se agotó la cuota de búsquedas del día.
429	`snippet_quota_exceeded`	Se agotó la cuota de fragmentos del día. Las búsquedas sin fragmentos siguen funcionando.

Qué hacer en cada caso

400: la solicitud es incorrecta y repetirla no servirá de nada. El campo parameter indica cuál es el problema.
401, 403: tu clave o tu plan. No vale la pena reintentar hasta que algo cambie.
429 too_many_requests: espera retry_after segundos y repite. No se consumió nada.
429 quota_exceeded: la cuota vuelve a la siguiente medianoche UTC; retry_after indica cuánto falta. Reintentar antes no servirá de nada.
5xx: es cosa nuestra. Reintenta con esperas cada vez más largas.

Errores y formatos

Los errores se devuelven en JSON, o en XML si se pidió format=xml. Los formatos planos no tienen estructura para un error, así que una solicitud fallida que pidió csv recibe JSON; por eso, un cliente que lee CSV debería comprobar el código de estado en lugar de suponer que todo cuerpo con aspecto de respuesta 200 son filas.

Leer los códigos sin leer esta página

GET / enumera todos los códigos anteriores, con su significado, en JSON. No necesita clave, así que se puede crear un cliente para todo el conjunto sin que nadie abra un navegador.

curl https://api.publicwww.com/

Siguiente Ejemplos de código