Errors

What each error status means, and what to do about it.

On this page

Errors are JSON with a detail field. It is a message, an object with a code and a message, or, for validation errors, a list of problems.

Error bodies

{"detail": "Website not found"}

{"detail": {"code": "crawler_response_invalid", "message": "The site's crawler returned a redirect chain answer that does not match the contract"}}

{"detail": [{"loc": ["query", "limit"], "msg": "Input should be less than or equal to 500", "type": "less_than_equal"}]}

Status codes

401
What it means
The token is missing, wrong, revoked, or expired.
What to do
Send Authorization: Bearer <token>. Create a new API key, or refresh the OAuth token.
403
What it means
The token lacks a scope, an API key called an endpoint that writes, or the person's role is too low.
What to do
Read detail. Grant the scope, use OAuth for writes, or ask an owner or admin.
404
What it means
The site, URL, or report is not in this workspace.
What to do
Check the id, and that the token belongs to the workspace that has the site.
409
What it means
The request clashes with the current state, for example an Idempotency-Key reused with a different request.
What to do
Read detail. Send a new key for a new request.
422
What it means
The request did not match the schema.
What to do
Fix each problem detail lists: loc says where.
429
What it means
Rate limited.
What to do
Wait for Retry-After seconds, then retry.
502
What it means
The site's crawler answered outside the contract (crawler_response_invalid).
What to do
Retry later. If you sent a write, read the resource first to see whether it was applied.
503
What it means
Temporarily unavailable.
What to do
Read detail: it says whether a retry is safe.

Status codes
Status	What it means	What to do
401	The token is missing, wrong, revoked, or expired.	Send `Authorization: Bearer <token>`. Create a new API key, or refresh the OAuth token.
403	The token lacks a scope, an API key called an endpoint that writes, or the person's role is too low.	Read `detail`. Grant the scope, use OAuth for writes, or ask an owner or admin.
404	The site, URL, or report is not in this workspace.	Check the id, and that the token belongs to the workspace that has the site.
409	The request clashes with the current state, for example an `Idempotency-Key` reused with a different request.	Read `detail`. Send a new key for a new request.
422	The request did not match the schema.	Fix each problem `detail` lists: `loc` says where.
429	Rate limited.	Wait for `Retry-After` seconds, then retry.
502	The site's crawler answered outside the contract (`crawler_response_invalid`).	Retry later. If you sent a write, read the resource first to see whether it was applied.
503	Temporarily unavailable.	Read `detail`: it says whether a retry is safe.

Errors carry a detail message. A missing scope also names the accepted scopes in the WWW-Authenticate header.

401
detail
Bearer token is required
What it means
The request had no bearer token.
401
detail
Invalid or inactive API key
What it means
The key is wrong, revoked, or rotated.
401
detail
Invalid or expired OAuth access token
What it means
Refresh the token or connect again.
403
detail
Integration token requires one of these scopes: …
What it means
The token has none of the scopes the endpoint accepts.
403
detail
Write operations require OAuth user consent; API keys remain read-only
What it means
An API key called an endpoint that writes.
403
detail
Team management requires OAuth user consent; API keys remain read-only
What it means
An API key called a team endpoint.
403
detail
Workspace editor access is required
What it means
The person's workspace role is below editor.
403
detail
Workspace owner or admin access is required
What it means
Team management needs an owner or admin.

Authentication errors
Status	detail	What it means
401	Bearer token is required	The request had no bearer token.
401	Invalid or inactive API key	The key is wrong, revoked, or rotated.
401	Invalid or expired OAuth access token	Refresh the token or connect again.
403	Integration token requires one of these scopes: …	The token has none of the scopes the endpoint accepts.
403	Write operations require OAuth user consent; API keys remain read-only	An API key called an endpoint that writes.
403	Team management requires OAuth user consent; API keys remain read-only	An API key called a team endpoint.
403	Workspace editor access is required	The person's workspace role is below editor.
403	Workspace owner or admin access is required	Team management needs an owner or admin.

Last updated October 29, 2026