{"templateId":"../../../@theme/Templates/Wide.tsx","sharedDataIds":{"sidebar":"sidebar-guides/developer/errors/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["sub-header","error-code-heading","section","panel-left","panel-right","admonition"]},"type":"markdown"},"seo":{"title":"Authentication and access errors","siteUrl":"https://docs.wise.com","projectTitle":"Wise Platform","description":"Handle invalid credentials, invalid tokens, access denials, and SCA responses from the Wise API.","keywords":["authentication errors","invalid token","401","403","SCA"]},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"authentication-and-access-errors","__idx":0},"children":["Authentication and access errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"span","attributes":{"class":"sub-header"},"children":["Handle invalid credentials, access denials, and SCA challenges."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Authentication errors indicate that Wise could not verify your credentials. Access errors indicate that the authenticated identity cannot perform the requested action. Both can use similar response formats, so inspect the HTTP status, error identifier, and response headers together."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On this page:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#request-an-access-token"},"children":["Request an access token"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#call-protected-operations"},"children":["Call protected operations"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#distinguish-401-from-403"},"children":["Distinguish 401 from 403"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#handle-an-invalid-access-token"},"children":["Handle an invalid access token"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#handle-an-sca-response"},"children":["Handle an SCA response"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#map-messages-safely"},"children":["Map messages safely"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#related-authentication-guides"},"children":["Related authentication guides"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/developer/errors#choose-a-recovery-action"},"children":["shared handling guidance"]}," for choosing an action, displaying messages, and retrying safely."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"request-an-access-token","__idx":1},"children":["Request an access token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Endpoint:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /oauth/token"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/oauth-token/oauthtokencreate"},"children":["create an access token operation"]}," for the current request and response schema."]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"invalid_request"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The authentication or token request is missing a required value or is malformed."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Compare the request with the applicable token operation."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add or correct the required parameters."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not retry the unchanged request."]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"invalid_client"},"children":[]},{"$$mdtype":"Tag","name":"Section","attributes":{},"children":[{"$$mdtype":"Tag","name":"PanelLeft","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Wise cannot authenticate the client application."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify the current client credentials and authentication method."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check the header format without writing secrets to logs."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry only after correcting the client authentication."]}]},{"$$mdtype":"Tag","name":"PanelRight","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example error response"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"error\": \"invalid_client\",\n  \"error_description\": \"Client authentication failed\"\n}\n","lang":"json"},"children":[]}]}]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"invalid_grant"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The OAuth grant is invalid, expired, revoked, or already used."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Restart the applicable authorisation flow or obtain a new grant."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Stop using the rejected value."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not repeatedly submit the same grant."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"call-protected-operations","__idx":2},"children":["Call protected operations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Endpoint:"]}," Any operation that requires an access token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following codes can apply across authenticated API domains. Interpret them with the operation, HTTP status, and response headers."]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"invalid_token"},"children":[]},{"$$mdtype":"Tag","name":"Section","attributes":{},"children":[{"$$mdtype":"Tag","name":"PanelLeft","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The bearer token is expired, revoked, replaced, or otherwise invalid."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Discard the rejected token."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Obtain and distribute a valid token before sending more requests."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry the failed request once with the new token only when replay is safe, following the operation's idempotency rules where applicable. If renewal or replay fails, stop safely, show an appropriate customer message, and record the issue for investigation."]}]},{"$$mdtype":"Tag","name":"PanelRight","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example error response"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"error\": \"invalid_token\",\n  \"error_description\": \"Invalid token\"\n}\n","lang":"json"},"children":[]}]}]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"missing_token"},"children":[]},{"$$mdtype":"Tag","name":"Section","attributes":{},"children":[{"$$mdtype":"Tag","name":"PanelLeft","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The request does not include a bearer token where one is required."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer <token>"]}," using a token valid for the operation."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check intermediaries that may remove sensitive headers."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry after adding the token."]}]},{"$$mdtype":"Tag","name":"PanelRight","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example error response"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"error\": \"missing_token\",\n  \"error_description\": \"Missing token\"\n}\n","lang":"json"},"children":[]}]}]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"unauthorized"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The request is not authenticated or the authenticated identity cannot perform the operation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use the HTTP status and response headers to distinguish authentication from permission or SCA problems."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify the token, profile, and operation."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry only after correcting the authentication or access context."]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"forbidden"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The authenticated identity is not permitted to access the operation or resource."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify the token type, profile, ownership, and integration permissions."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Display a generic permission message."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not retry unchanged."]},{"$$mdtype":"Tag","name":"ErrorCodeHeading","attributes":{"code":"security.error"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The authenticated identity cannot access the requested operation or resource."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What to do"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify authentication, profile ownership, and permissions."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not reveal whether an inaccessible resource belongs to another user."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry conditions"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry only after correcting the access context."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"distinguish-401-from-403","__idx":3},"children":["Distinguish 401 from 403"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the HTTP status as the first decision point:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," can mean invalid credentials or a token that cannot access the requested profile. Inspect the identifier before renewing the token."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}," usually means that Wise recognised the request but did not permit the action."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An SCA-protected operation also uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]},". Check the documented SCA headers before treating it as a permanent access denial."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Do not refresh on every access error"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Refreshing a token does not fix a profile ownership, permission, or SCA issue. Refresh only when the response indicates that the token is invalid."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handle-an-invalid-access-token","__idx":4},"children":["Handle an invalid access token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To recover from an invalid access token:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Stop using the rejected access token."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Obtain a new token using the appropriate grant."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store and distribute the new token before sending more requests."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Retry the failed request once with the new token, following the operation's idempotency rules where applicable."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If token renewal or replay fails, stop safely, show an appropriate customer message, and record the issue for investigation. Do not expose token details to the customer."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For user access tokens, centralise refreshes so 2 services do not invalidate each other's tokens. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/developer/auth-and-security/refresh-tokens"},"children":["refresh tokens"]}," for concurrency and storage guidance."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handle-an-sca-response","__idx":5},"children":["Handle an SCA response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An SCA-protected operation can return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}," with Wise-specific response headers. Inspect the headers before deciding that the caller lacks permission."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-2FA-Approval"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-2FA-Approval-Result"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Complete the required SCA challenge."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Retry the protected operation with the approved one-time token."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/developer/auth-and-security/sca-and-2fa"},"children":["SCA and two-factor authentication"]}," for the supported flow."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"map-messages-safely","__idx":6},"children":["Map messages safely"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Authentication and access messages are developer-facing by default:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not display ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_description"]}," directly to an end user."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not reveal whether another profile owns a requested resource."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Map invalid credentials to a generic authentication message."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Map access denials to a generic permission message."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Log the error identifier and operation without logging tokens or secrets."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-authentication-guides","__idx":7},"children":["Related authentication guides"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/developer/auth-and-security/client-credentials-token"},"children":["Client credentials tokens"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/developer/auth-and-security/user-access-token"},"children":["User access tokens"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/developer/auth-and-security/refresh-tokens"},"children":["Refresh tokens"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/developer/auth-and-security/oauth-2-setup"},"children":["OAuth 2.0 setup"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/developer/auth-and-security/mtls"},"children":["Mutual TLS"]},"."]}]}]},"headings":[{"value":"Authentication and access errors","id":"authentication-and-access-errors","depth":1},{"value":"Request an access token","id":"request-an-access-token","depth":2},{"value":"Call protected operations","id":"call-protected-operations","depth":2},{"value":"Distinguish 401 from 403","id":"distinguish-401-from-403","depth":2},{"value":"Handle an invalid access token","id":"handle-an-invalid-access-token","depth":2},{"value":"Handle an SCA response","id":"handle-an-sca-response","depth":2},{"value":"Map messages safely","id":"map-messages-safely","depth":2},{"value":"Related authentication guides","id":"related-authentication-guides","depth":2}],"frontmatter":{"template":"../../../@theme/Templates/Wide.tsx","seo":{"title":"Authentication and access errors","description":"Handle invalid credentials, invalid tokens, access denials, and SCA responses from the Wise API.","keywords":["authentication errors","invalid token","401","403","SCA"]},"markdown":{"toc":{"hide":true}}},"lastModified":"2026-09-22T05:59:17.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/developer/errors/authentication","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}