Errors

A failed request has a status from 400 up and one body shape. Branch on code. The message is for a person and may be reworded.

Docs menu

JSON

{
  "error": {
    "type": "invalid_request",
    "code": "too_many_pages",
    "message": "This check has more pages than your account may send in one check.",
    "param": "pages",
    "request_id": "req_0Lr8L2F9yU1hFe3vC8xDmL"
  }
}
  • type is the family. code is stable: it never changes meaning within v1, and new codes are only added.
  • param names the field at fault, when one is.
  • request_id is on every answer, in the Request-Id header too. Quote it when you write to us.
  • A message never repeats what you sent, so it is safe to log.

Codes

invalid_request

CodeStatusMeaning
body_not_json400The request body must be a JSON object.
body_too_large413The request body is larger than 256 KB.
unknown_parameter400The request has a parameter this endpoint does not accept.
parameter_missing400A required parameter is missing.
parameter_invalid400A parameter has a value this endpoint does not accept.
pages_empty400Give at least one page address.
too_many_pages400This check has more pages than your account may send in one check.
no_usable_page400None of the page addresses could be used. Each one is listed under rejected with its reason.
client_domain_invalid400The client domain is not a public web domain, such as example.com.
text_missing400A text check needs the text that was placed.
text_too_short400The text is too short to recognize on a page. Send at least 40 words.
text_too_long400The text is longer than 50,000 characters.
text_given_for_link_check400A link check takes no text. Leave text out, or use mode text.
mode_unknown400The mode must be auto, text or link_check.
schedule_unknown400The schedule must be daily, weekly or day7_day30.
brand_name_invalid400The brand name must be 1 to 80 characters.
logo_url_invalid400The logo address must be an https address.
brand_color_invalid400The brand color must be a hex color such as #1d47c5.
release_text_too_long400The release is longer than the package allows.
release_text_missing400This package needs the release text.
brief_missing400This package needs a brief for us to write from.
website_invalid400The website must be a public https address on your own domain.
screen_statement_missing400Confirm that the release has none of the refused content and that every link is yours.
idempotency_key_invalid400The Idempotency-Key header must be 1 to 255 printable characters.
cursor_invalid400The starting_after cursor does not name an object in this list.
limit_invalid400The limit must be a whole number from 1 to 100.
date_range_invalid400The dates must be YYYY-MM-DD, from before to, at most 92 days apart.
webhook_url_invalid400The webhook address must be a public https address without a user name or an IP address.
event_type_unknown400One of the event types is not a PressProve event.
scope_unknown400One of the scopes is not a PressProve scope.
key_name_invalid400The key name must be 1 to 60 characters.

authentication_error

CodeStatusMeaning
missing_api_key401Send your API key as Authorization: Bearer <key>.
invalid_api_key401The API key is not valid.
api_key_revoked401The API key has been revoked.

permission_error

CodeStatusMeaning
missing_scope403The API key does not have the scope this endpoint needs.
account_frozen403The account is frozen. Read requests still work; contact us to lift it.
account_not_onboarded403Finish the account details in the console first.
live_mode_closed403Live mode is not open yet. Test keys work now.
releases_closed403Publishing by API is not open.
test_only_endpoint403This endpoint works with test keys only.
country_blocked403We cannot serve this country.
identity_level_insufficient403Publishing needs the account to pass our business identity checks first.
business_details_required403Add your business details in the console before the first top-up.
pack_not_available403This top-up pack is not available to this account yet.
package_not_available403This package cannot be ordered through the API.
permission_denied403Your role in this workspace does not allow this.
limit_reached403The workspace has reached its limit of seats or client projects.

not_found

CodeStatusMeaning
not_found404No such object.
route_not_found404No such endpoint. The reference lists every one.

method_not_allowed

CodeStatusMeaning
method_not_allowed405This endpoint does not take that method. The Allow header lists the ones it takes.

conflict

CodeStatusMeaning
check_not_completed409The check has not completed.
check_not_cancelable409Only a queued check can be canceled.
monitor_not_active409The monitor is not active.
monitor_not_paused409The monitor is not paused.
monitor_ended409The monitor has ended.
pdf_not_ready409The PDF is not ready yet.
release_not_approvable409The release has no draft waiting for approval.
draft_changed409The draft has changed since you read it. Read the release again.
changes_already_used409The one round of changes has been used.
workspace_changed409You switched workspace in another tab. Reload the page and try again.

idempotency_error

CodeStatusMeaning
idempotency_key_reused422This Idempotency-Key was used with a different request.

insufficient_balance

CodeStatusMeaning
insufficient_balance402The balance is too low for this request.

rate_limited

CodeStatusMeaning
rate_limited429Too many requests. Wait for the time in Retry-After.
account_daily_limit429The account has used its pages for today (UTC).
pending_pages_limit429The account has too many pages waiting. Wait for a check to finish.
target_host_limit429That website has had as many checks as we make in a day. Try again tomorrow.
monitor_limit429The account has as many monitors or monitored pages as it may have.
key_limit429The account has as many keys as it may have in this mode.
webhook_endpoint_limit429The account has as many webhook endpoints as it may have.
reports_daily_limit429The account has made as many reports as it may today (UTC).
test_event_limit429This endpoint has had as many test events as it may in an hour. Try again later.
free_allowance_paused429Free checks are paused for today across PressProve. Top up to keep checking now, or try again tomorrow (UTC).
new_account_topup_limit429A new account may top up once a day and at most US$100 in its first 30 days.
daily_work_budget_reached429The account has used its checking time for the last 24 hours. Work already queued still finishes; try again after the time in Retry-After.
new_account_spend_limit429A new account may spend a limited number of credits in 24 hours. The limit lifts as the account ages.

api_error

CodeStatusMeaning
internal_error500Something went wrong on our side. Retry with the same Idempotency-Key.

unavailable

CodeStatusMeaning
engine_unavailable503Live checks are not available right now.
payments_unavailable503Payments are not available right now.

Pages we refuse in a check

When some pages of a check cannot be used, the check still runs for the rest. The refused ones are listed in rejected with one of these codes and are never charged. If none can be used the request fails with no_usable_page.

CodeMeaning
url_too_longThe address is longer than 2,048 characters.
unsupported_scheme:The address is not a web address (for example mailto: or ftp:).
not_a_web_urlThe address is not an http or https address.
not_a_urlThe text could not be read as an address.
no_hostThe address has no host name.
host_is_localhostThe address points at a local computer.
host_is_not_publicly_resolvableThe address is on a private network name.
host_is_ip_addressThe address is an IP address, not a website name.
host_has_no_dotThe host name is not a public domain.
url_carries_credentialsThe address carries a user name or password.
no_url_found_on_lineA line looked like an address but none could be read.
page_has_credentialsThe address carries a user name or password. We never send credentials.
host_opted_outThe owner of this website has asked us not to check it.
host_personal_socialWe do not check personal social-media pages or profiles.

A code that ends in a colon, such as unsupported_scheme:, is followed by a detail.

What to do

  • 400, 402, 403, 404, 409, 422: fix the request or the account. Retrying the same request will not help.
  • 429: wait for the time in Retry-After, then retry.
  • 500 and 503: retry with the same Idempotency-Key, a little later each time.