Errors return a JSON body with a machine-readable code: 
{
  "error": "This key is not granted cloud_security",
  "code": "product_not_granted",
  "request_id": "5f0c1c2e-8a7b-4f3e-9d61-2b8f7a1e4c90"
}
Branch on code, not on the error message, which may change. request_id matches the X-Request-Id response header; include it when you contact support.

​
Error codes

StatuscodeCauseWhat to do
400product_requiredproduct is missingAdd product
400unknown_productproduct is not a product keyUse a value from whoami
400invalid_parameterA parameter has an unknown value or the wrong formatFix the parameter; the message names it
400invalid_cursorThe cursor is malformed, or belongs to a request with different parametersResend the original parameters, or drop the cursor
400credentials_in_queryA key was sent in the query stringSend it in a header
400updated_since_out_of_rangeupdated_since is older than the product’s history windowRun a snapshot without updated_since
401missing_api_key, wrong_key_type, invalid_api_key, revoked_api_key, expired_api_keyThe key is missing or not usableSee Authentication
403org_inactiveThe organization’s subscription is paused or has endedContact the organization’s admin
403invalid_scopeThe key’s stored scope can’t be readEdit the key in the dashboard
403product_not_grantedThe key’s scope doesn’t include this product. For /controls and /frameworks, the key lacks the finding types the controls are built fromEdit the key’s scope, or skip the product
403users_not_grantedThe key isn’t granted User details, which /users needsEdit the key’s scope to include User details
403product_not_entitledThe organization’s plan doesn’t include this product, or none of the key’s finding types for itSkip the product; whoami shows readable: false
404not_foundNo such finding or endpoint within the key’s scopeDrop the id from your copy
409cursor_staleThe key’s scope or the organization’s plan changed while pagingRestart without a cursor
429rate_limitedToo many requests. See Rate limitsWait Retry-After seconds
500internal_errorAn unexpected failureRetry with backoff; contact support with the request_id if it persists
503ledger_initializingA ledger product’s first history build hasn’t finishedWait Retry-After seconds; see Ledger products
503gate_unavailable, scope_unavailableA temporary failure checking the key or loading its scopeRetry after Retry-After seconds, or with backoff if the header is absent

​
Filters outside the key’s scope

Asking for data the key can’t read is not an error:
  • finding_type values outside the key’s scope return no rows and are listed in meta.scope.excluded_finding_types.
  • asset_id values outside the key’s scope match nothing.
  • A filter that a product can’t apply is listed in meta.scope.ignored_filters. For example, the issues product ignores asset_id.
An unknown finding_type for the product, as opposed to one the key can’t read, is a 400 invalid_parameter.