{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Errors"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"errors","__idx":0},"children":["Errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every error response from the Titan Public API is a JSON object with a stable, machine-readable shape. Human-readable text is helpful for logging; the structured fields are what your integration should branch on."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"response-shape","__idx":1},"children":["Response shape"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"error\": {\n    \"code\": \"invalid_argument\",\n    \"message\": \"page_size must be between 1 and 500.\",\n    \"field\": \"page_size\",\n    \"request_id\": \"req_01HYZ8V3X5A9K2QW6T3P0RJDNS\",\n    \"docs_url\": \"https://docs.titanapi.securityscorecard.io/docs/guides/errors#invalid_argument\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Present"},"children":["Present"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["always"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Stable machine-readable identifier. Branch on this."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["always"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Human-readable description. May change wording between releases."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["field"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["only on validation errors"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Which request field caused the failure."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["always"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Correlation ID. Include this when reporting bugs."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["docs_url"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["when applicable"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Deep link to the specific error's documentation."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"status-codes","__idx":2},"children":["Status codes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The HTTP status code groups errors into the categories below. Match on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.code"]},", not on status, when your integration needs fine-grained branching — a single status can carry multiple codes."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Category"},"children":["Category"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example codes"},"children":["Example codes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Malformed or invalid request"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_argument"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["missing_required_field"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authentication failed"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unauthenticated"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token_expired"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authenticated but not permitted"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["permission_denied"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["insufficient_scope"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Resource does not exist or is not visible"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not_found"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conflict with existing state"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["already_exists"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["precondition_failed"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["410"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Endpoint has been retired"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endpoint_gone"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payload validated but semantically rejected"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unprocessable_entity"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rate limit exceeded"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rate_limit_exceeded"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Server error — safe to retry"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internal"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["503"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Service temporarily unavailable"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unavailable"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-to-do","__idx":3},"children":["What to do"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["4xx"]}," other than ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}]}," — treat as permanent for this request. Do not retry without changing the request. Log ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request_id"]}," for support."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}]}," — honour the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Retry-After"]}," header. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/guides/usage-limits"},"children":["Usage Limits"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5xx"]}]}," — retry with exponential backoff (base 1s, factor 2, jitter, cap 30s). If a retry succeeds, no further action. If retries exhaust, escalate with the earliest ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request_id"]}," you observed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["410"]}," (retired)"]}," — the endpoint is gone. Migrate to the successor documented in the endpoint's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Link: <url>; rel=\"successor-version\""]}," header."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"logging-errors","__idx":4},"children":["Logging errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["At minimum, log:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["HTTP status code"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.code"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.request_id"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The endpoint and method you called (not the full request body — it may contain sensitive fields)."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not log access tokens, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLIENT_SECRET"]},", or full request/response payloads by default — they may contain sensitive fields."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"reporting-a-bug","__idx":5},"children":["Reporting a bug"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When opening a support ticket, include:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request_id"]}," — required. Without it we cannot correlate your call to server logs."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["HTTP status and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.code"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Approximate timestamp (UTC)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Minimal request example (method, path, headers other than ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["What you expected vs. what you observed."]}]}]},"headings":[{"value":"Errors","id":"errors","depth":1},{"value":"Response shape","id":"response-shape","depth":2},{"value":"Status codes","id":"status-codes","depth":2},{"value":"What to do","id":"what-to-do","depth":2},{"value":"Logging errors","id":"logging-errors","depth":2},{"value":"Reporting a bug","id":"reporting-a-bug","depth":2}],"frontmatter":{"seo":{"title":"Errors"}},"lastModified":"2026-08-19T12:45:50.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/guides/errors","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}