{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["json-schema","admonition"]},"type":"markdown"},"seo":{"title":"Error Handling"},"dynamicMarkdocComponents":["openapi"],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"error-handling","__idx":0},"children":["Error Handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The DeepCredentials API uses standard HTTP status codes and structured error responses."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-response-format","__idx":1},"children":["Error response format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All error responses follow this structure:"]},{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g. `not_found`, `unauthenticated`). See table below."},"message":{"type":"string","description":"Human-readable error description."},"details":{"type":"object","description":"Optional structured data with additional context."}}},"options":{},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code (e.g. `not_found`, `unauthenticated`). See table below."},"message":{"type":"string","description":"Human-readable error description."},"details":{"type":"object","description":"Optional structured data with additional context."}}}}}},"schemaResolvedErrors":[]},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-codes","__idx":2},"children":["Error 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":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"HTTP Status"},"children":["HTTP Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Retryable"},"children":["Retryable"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ok"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["200"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No error."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_argument"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request validation failed (missing field, invalid format)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unauthenticated"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["401"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing, invalid, or expired credentials."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No*"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["permission_denied"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["403"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Valid credentials, but the token lacks the scope required by this endpoint."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not_found"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["404"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Resource does not exist or is not accessible to this credential."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["resource_exhausted"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["429"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rate limit exceeded."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes (with backoff)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed_precondition"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Operation cannot be performed in the current state (e.g. an illegal credential-status transition)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internal"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["500"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Internal server error."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes (with backoff)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unavailable"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["503"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Service temporarily unavailable."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes (with backoff)"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["* For expired Bearer tokens: re-authenticate against DeepCloud's SSO token endpoint to get a new access token (see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/guides/authentication/service-users"},"children":["Authentication — Service Users"]},")."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authentication-errors","__idx":3},"children":["Authentication errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Tokens are issued by DeepCloud's SSO realm, not by DeepCredentials. Token-endpoint failures (e.g. wrong ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]},", disabled service user, missing scope on the partner client) follow OAuth 2.0 standard error responses from Keycloak:"]},{"$$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":"Error"},"children":["Error"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"HTTP Status"},"children":["HTTP Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_request"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing or unsupported parameter on the token call."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_client"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["401"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]}," rejected by Keycloak."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_grant"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["username"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["password"]}," rejected, or the service user is disabled."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unauthorized_client"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["403"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The partner client isn't configured for the requested grant type or scope."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the token endpoint succeeds but the API still rejects the request: the response will use the DeepCredentials error format above. The most common cause of a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}," from a B2B endpoint is a scope your partner client wasn't configured to grant — inspect the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scope"]}," claim on the issued JWT (it lists what was actually granted, which may be a subset of what you requested)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"retry-strategy","__idx":4},"children":["Retry strategy"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For retryable errors (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["503"]},"), use exponential backoff:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Wait 1 second, then retry."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If it fails again, wait 2 seconds."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Double the wait time on each subsequent retry (4s, 8s, 16s...)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cap at 60 seconds maximum wait."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Stop after 5 retries."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add random jitter (±20%) to avoid thundering herd effects."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import time\nimport random\n\ndef retry_with_backoff(fn, max_retries=5):\n    for attempt in range(max_retries):\n        try:\n            return fn()\n        except RetryableError:\n            if attempt == max_retries - 1:\n                raise\n            wait = min(60, (2 ** attempt)) * (0.8 + 0.4 * random.random())\n            time.sleep(wait)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Do not retry client errors"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Never retry ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}," errors — these indicate a problem with your request that must be fixed in code."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":5},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/guides/verification-flow"},"children":["Verification Flow"]}," — Handle all session statuses."]}]}]},"headings":[{"value":"Error Handling","id":"error-handling","depth":1},{"value":"Error response format","id":"error-response-format","depth":2},{"value":"Error codes","id":"error-codes","depth":2},{"value":"Authentication errors","id":"authentication-errors","depth":2},{"value":"Retry strategy","id":"retry-strategy","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"seo":{"title":"Error Handling"}},"lastModified":"2026-06-03T20:39:07.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/guides/error-handling","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}