Local prototype · simulated data

Errors

Errors use one envelope with a stable code to branch on, a human message, and a request_id to report.

Envelope

JSON

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_query_length",
    "message": "q must be 2 to 100 characters.",
    "request_id": "req_0000000000000000docs",
    "doc_url": "https://docs.example.com/errors#invalid_query_length",
    "param": "q"
  }
}

Branch on error.code, never on message. Messages may change; codes will not change without a new API version. User input is never echoed back.

Error codes

All error codes
Code	HTTP	Type	Meaning	What to do
`missing_api_key`	401	`authentication_error`	No `Authorization: Bearer` header was sent.	Send a test key in the header.
`invalid_api_key`	401	`authentication_error`	The key is unknown or has been revoked.	Check the key in the console; create a new one if it was revoked.
`live_keys_disabled`	403	`permission_error`	A `_live_` key was used. Live keys do not exist yet.	Use a test key.
`origin_not_allowed`	403	`permission_error`	A publishable key (or a demo/waitlist call) came from an origin that is not on the allowlist.	Add the origin to the key, or call from an allowed origin.
`secret_key_in_browser`	403	`permission_error`	A secret key was sent with an `Origin` header, which means it is running in a browser.	Move the call to your server, or use a publishable key.
`secret_key_required`	403	`permission_error`	The endpoint (for example `/v1/usage`) needs a secret key.	Call it from your server with a secret key.
`key_in_url`	400	`invalid_request`	An API key was sent as a `key` or `api_key` query parameter.	Send keys only in the Authorization header. URLs end up in logs.
`invalid_query_length`	400	`invalid_request`	`q` is shorter than 2 or longer than 100 characters.	Wait for two characters before calling; trim long input.
`invalid_query_characters`	400	`invalid_request`	`q` contains characters that never appear in a street address.	Strip markup and control characters.
`invalid_limit`	400	`invalid_request`	`limit` is not an integer from 1 to 10.	Use 1–10 (default 5).
`invalid_state`	400	`invalid_request`	`state` is not a two-letter code.	Use USPS codes such as `NY`.
`invalid_zip`	400	`invalid_request`	`zip` is not 1–5 digits.	Send a ZIP or ZIP prefix.
`invalid_city`	400	`invalid_request`	`city` is too long or has unsupported characters.	Send the plain city name.
`invalid_id`	400	`invalid_request`	The suggestion id is malformed.	Use an id returned by autocomplete.
`invalid_secondary`	400	`invalid_request`	The unit filter is too long or has unsupported characters.	Send something like `4` or `Apt 4`.
`address_not_found`	404	`not_found`	No address has this id.	Run autocomplete again; ids can change when the underlying data version changes.
`route_not_found`	404	`not_found`	Unknown endpoint.	Check the path against the reference.
`method_not_allowed`	405	`invalid_request`	The HTTP method is not supported here.	See the `Allow` response header.
`rate_limit_exceeded`	429	`rate_limited`	Too many requests in the current window.	Wait for `Retry-After` seconds, then retry.
`internal_error`	500	`api_error`	Unexpected error in the prototype.	Retry with backoff; report the `request_id`.
`invalid_json`	400	`invalid_request`	The request body is not a JSON object.	Send a JSON object.
`unsupported_media_type`	415	`invalid_request`	The body was not sent as `application/json`.	Set `Content-Type: application/json`.
`payload_too_large`	413	`invalid_request`	The body is larger than 4 KB.	Send only the documented fields.
`invalid_body`	400	`invalid_request`	The waitlist body is not an object.	Send a JSON object.
`invalid_email`	400	`invalid_request`	The email address is not valid.	Ask the user to correct it.
`consent_required`	400	`invalid_request`	The waitlist privacy notice was not accepted.	Show the notice and collect explicit consent.
`stale_notice_version`	400	`invalid_request`	The privacy notice version sent is not the current one.	Reload the page so the user sees the current notice.
`invalid_field`	400	`invalid_request`	An optional waitlist field is invalid (see `param`).	Fix the named field.
`invalid_or_expired_token`	400	`invalid_request`	A confirmation, unsubscribe or deletion link is invalid, used or expired.	Request a new link.