Errors

Look up Scrut API error codes for data endpoints and the token endpoint, and learn which errors are safe to retry.

The Scrut API uses HTTP status codes to tell you whether a request succeeded. When a request fails, the response body includes an error code that explains why.

Data Endpoint Errors

Errors from /v1 endpoints use this shape:

{
  "error": {
    "code": "validation_failed",
    "message": "Request validation failed.",
    "details": [
      {
        "field": "status",
        "message": "status contains unknown value(s): unknown"
      }
    ]
  },
  "meta": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

HTTP status	Error code	What it means
400	`validation_failed`	A parameter or body field is invalid. Check `details` for the field.
400	`idempotency_key_required`	A write request is missing the `Idempotency-Key` header.
401	`unauthorized`	The Bearer token is missing, malformed, or invalid.
401	`token_revoked`	The credential that issued the token was revoked.
401	`token_credential_expired`	The credential that issued the token has expired. Create a new credential.
401	`token_stale`	The token is stale. Request a new token.
403	`forbidden`	The credential doesn't have the scope this endpoint requires.
403	`plan_restricted`	Your Scrut plan doesn't include access to this resource.
404	`not_found`	The requested resource doesn't exist.
409	`conflict`	The request conflicts with the resource's current state.
409	`idempotency_key_reused`, `idempotency_request_in_progress`	The idempotency key conflicts with an earlier or in-progress request.
429	`rate_limit_exceeded`	You exceeded the rate limit. Wait for the time in `Retry-After`.
500	`internal_error`	An unexpected error occurred.
503	`upstream_unavailable`	A dependent service is temporarily unavailable. Retry later.

Token Endpoint Errors

Errors from /oauth/token follow the OAuth format:

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials. Verify client_id and client_secret, or create a new credential in the Developer Console."
}

HTTP status	Error code	What it means
400	`invalid_request`	`grant_type` is wrong or a required field is missing.
401	`invalid_client`	The client ID or secret is wrong, or the credential is revoked or expired.
429	`temporarily_unavailable`	You exceeded the token endpoint rate limit.
503	`temporarily_unavailable`	The authorization server is temporarily unavailable. Retry later.

Common Fixes

``**** on a vulnerability: The vulnerabilityId returned by the API is already URL-encoded. Paste it into the path as is. See Requests and Responses.
``**** on a write: The credential is Read Only. Create a Read & Write credential. See Scopes and Permissions.
``**** after an hour: Your access token expired. Request a new token. See Authentication and Access Tokens.
``****: You reused a key with a different body. Generate a new key for each new write. See Idempotency.

Which Errors to Retry

Error	Retry?
`429`	Yes, after the number of seconds in `Retry-After`. See Rate Limits.
`503`	Yes, after a short wait.
`409 idempotency_request_in_progress`	Yes, with the same `Idempotency-Key`, after the original request finishes.
`400`, `403`, `404`, other `409` errors	No. Fix the request first.
`401`	Only after you request a new token, or create a new credential if it was revoked or expired.

Pro Tip! Include the requestId from meta or the X-Request-Id header when you contact support about a failed request. It helps us trace the exact call.

Contact support@scrut.io for further assistance.

Was this page helpful?