Use stable codes for client behavior.

Errors use stable machine-readable codes so callers can distinguish validation, auth, quota, coverage, and layer selection failures without parsing prose messages.

JSON ErrorResponse

{
  "error": {
    "code": "layer_not_available",
    "message": "The requested layer selection is not available to this account.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Statuses

HTTP status maps to the failure class.

Status	Meaning
`400`	Invalid query parameter shape.
`401`	Missing or invalid bearer API key.
`402`	Monthly quota exhausted.
`403`	Requested layer selection is well-formed but unavailable to the authenticated account. `layer_entry_cap_exceeded` means the account is at its plan's layer-entry capacity; archive entries or upgrade. `topup_requires_paid_plan` means top-ups are available on Startup and Business.
`405`	Only `GET` is supported.
`422`	Recognized but unsupported search shape.
`429`	`rate_limited` means the per-account burst limit was exceeded: 120 requests per minute on every plan.
`500`	Generic internal error.
`503`	Coverage or quota gate is temporarily unavailable.

Headers

Quota and retry metadata travel in headers.

Header	Use
`X-Request-ID`	Server-generated request identifier for support and debugging.
`X-Quota-Limit`	Current quota period limit.
`X-Quota-Remaining`	Remaining searches in the current quota period.
`X-Quota-Reset`	Current quota period reset time as Unix epoch seconds.
`Retry-After`	Seconds until the client should retry after rate limiting or temporary unavailability.