Errors

Every failure has the same shape and a stable code. Branch on the code - the message is written for people and may be reworded.

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

Some errors carry extra fields alongside those two: parameter for the one that was wrong, retry_after for how long to wait, limit and used for a spent quota.

Every code

Status	Code	When
400	`missing_query`	`query` was empty or absent.
400	`unsupported_query`	`filetype:css` or `filetype:js`, which work on the website only.
400	`unknown_format`	`format` is not one of the six.
400	`unknown_column`	`columns` names a field that does not exist.
400	`format_not_available`	A flat format was asked for where rows are not what is being returned.
400	`per_page_too_large`	`per_page` above your plan's row limit. The limit is in the error.
400	`invalid_json`	The POST body is not valid JSON.
401	`missing_key`	No `Authorization: Bearer` header.
401	`invalid_key`	The key does not name an account.
403	`plan_required`	The account has no paid plan.
404	`unknown_endpoint`	No such path. The known ones are listed in the error.
405	`method_not_allowed`	Read-only API. Use GET, or POST a JSON body.
429	`too_many_requests`	Arriving faster than two requests per 30 seconds.
429	`quota_exceeded`	The day's search allowance is spent.
429	`snippet_quota_exceeded`	The day's snippet allowance is spent. Searching without snippets still works.

What to do about each

400 - your request is wrong and repeating it will not help. The parameter field says which one.
401, 403 - your key or your plan. Not worth retrying until something changes.
429 too_many_requests - sleep retry_after seconds and repeat. Nothing was consumed.
429 quota_exceeded - the allowance returns at the next UTC midnight; retry_after says how far off that is. Retrying sooner will not help.
5xx - ours. Retry with a widening delay.

Errors and formats

Errors come back as JSON, or as XML when format=xml was asked for. The flat formats have no shape for an error, so a failed request that asked for csv gets JSON - which means a client reading CSV should check the status code rather than assume every 200-shaped body is rows.

Reading the codes without reading this page

GET / lists every code above, with its meaning, as JSON. It needs no key, so a client can be built against the whole set without anyone opening a browser.

curl https://api.publicwww.com/

Next Code examples