Skip to main content

Documentation index for AI agents: llms.txt. Every page here is also served as markdown: add .md to its address, or request it with Accept: text/markdown.

Errors

A failed request returns an HTTP status code. Most error bodies use the ErrorResponse shape below: a readable message and, where the endpoint sets one, a stable machine-readable code to branch on.

ErrorResponse fields

FieldTypeRequiredDescription
errorstringNoReadable message.
codestringNoStable machine-readable code when the endpoint sets one, for example SCOPE_DENIED, REGION_UNAVAILABLE or LOCATION_RESTRICTED.
messagestringNo
detailsanyNoValidation details when available.

Model page: ErrorResponse.

Status codes

  • 400: The request failed validation. The body says what to fix, often with a code.
  • 401: Credentials are missing, invalid or expired. Send an API key or sign in again.
  • 402: The workspace plan, trial or account state does not allow this action.
  • 403: The credentials work but are not allowed to do this: a missing scope, a role, a plan restriction or a session-only endpoint.
  • 404: The resource does not exist, or your workspace cannot see it.
  • 409: The request conflicts with the current state of the resource.
  • 410: The endpoint or resource was retired. The description names the replacement where there is one.
  • 422: The request was understood, but the target could not be processed.
  • 429: Too many requests. Wait before retrying, for the seconds in Retry-After where the response sends it.
  • 500: The request failed on our side. Retry later.
  • 502: A service the endpoint depends on did not answer. Retry later.
  • 503: The service is temporarily unavailable. Retry later.

Error codes

Codes the reference documents, with the status codes they come with. The endpoint pages show which responses mention each code.

  • API_ACCESS_NOT_IN_PLAN: 403
  • ASSERTIONS_CHANGED: 409
  • BASELINE_FILE_NOT_FOUND: 400
  • DEPENDENCY_EXISTS: 409
  • FEATURE_RESTRICTED: 403
  • INVALID_API_CONFIG: 400
  • INVALID_ASSERTION_PATTERN: 400
  • INVALID_KEYWORD_CONFIG: 400
  • INVALID_LOCATION: 400
  • LIMIT_EXCEEDED: 403
  • LOCATION_RESTRICTED: 403
  • LOCATION_UNSUPPORTED_FOR_TYPE: 400
  • NOT_AN_ALERT: 400
  • PAGE_NOT_TESTABLE: 503
  • PLAN_LIMIT_EXCEEDED: 403
  • RATE_LIMIT: 429
  • REGION_UNAVAILABLE: 400
  • SCOPE_DENIED: 403
  • SEAT_PAUSED_BY_PLAN: 403
  • SESSION_REQUIRED: 401, 403
  • SPEED_TEST_FAILED: 503
  • SPEED_TEST_SERVICE_BUSY: 503
  • SPEED_TEST_UNAVAILABLE: 503
  • SUBPAGE_NOT_ON_PLAN: 409
  • UNSUPPORTED_FIELD: 400
  • VISUAL_DISABLED: 409
  • VISUAL_TARGET_NOT_READY: 409
  • VISUAL_VIEWPORT_LIMIT: 403

Repeated 429 answers mean the client is over a limit, see Rate limits. Scope and plan errors are explained in Authentication.