API documentation · 9 of 9

Errors and limits

Every failed request answers with the same shape, so one piece of code can handle them all.

{
  "error": {
    "code": "project_not_found",
    "message": "No project with that id."
  }
}

Match on code. The message is for a person reading a log and may be reworded.

Error codes

Status	Code	Meaning
`400`	`invalid_body`	The body is not JSON, has a field the endpoint does not take, or one of the wrong type.
`400`	`invalid_url`	The `url` is not an http or https address.
`400`	`invalid_user_agent`	The `user_agent` is blank.
`400`	`credentials_required`	A `basic_auth` project was crawled without a `username`.
`400`	`invalid_project_id`, `invalid_page_id`	An id in the path is not a number.
`400`	`invalid_tab`	The `tab` is not one a page has.
`400`	`invalid_page`	The `page` asked for is past the last one.
`401`	`missing_credentials`	No bearer token was sent.
`401`	`invalid_credentials`	The key is unknown, malformed or revoked.
`403`	`insufficient_scope`	The key lacks the write scope.
`404`	`project_not_found`	No such project among yours.
`404`	`no_crawl`	The project has no finished crawl with pages yet.
`404`	`page_not_found`	No page with that id in the latest crawl.
`409`	`project_exists`	You already have a project for that URL. On create, `Location` points at it.
`409`	`crawl_in_progress`	The project is already being crawled.
`400`	`invalid_rule`	A custom rule is missing something or its pattern does not compile; the message says which.
`400`	`rule_limit`	The project already has 25 custom rules of that kind.
`404`	`rule_not_found`	No custom rule with that id in the project.
`413`	`body_too_large`	The body is over 64 KB.
`500`	`project_not_saved`, `crawl_not_started`	Something failed on the server. Try again, then check the server log.

Rate limits

Requests are counted per address, not per key: up to 60 a second in general, and 5 crawl starts a minute. Over the limit you get 429 Too Many Requests with a Retry-After header saying how many seconds to wait.

Pagination

Lists that page take ?page=, counting from 1, and answer with a pager. A value that is not a positive number is read as 1; a page past the end answers 400 invalid_page.

"pager": { "page": 2, "total_pages": 9 }