Troubleshoot OAuth errors

You will learn

Dealing with OAuth errors? This guide breaks down the potential errors you can experience when setting up OAuth and provides troubleshooting tips to help get you back on track using OAuth.

Learn more about how to authorize your app with OAuth..

Troubleshooting tips

The following list of troubleshooting tips is designed to help you resolve common OAuth errors.

Invalid client

If you get an invalid_client error, check that:

Your client id is correct.
[ID]:[SECRET] is base64 encoded.
The prefix is Basic and is base64 encoded.
You converted the base64 encoded credentials back to a string when concatenating with Basic. In some languages, the encoding creates bytes or some other format.
The authorization header on your request is correct.
- Example: Authorization: Basic <base64 encoded client_id:client_secret>.

Invalid grant type

If you get an invalid_grant_type error, check that:

You’re sending the correct grant type:
- Example: authorization_code, refresh_token.
Your request body is application/x-www-form-urlencoded.
- Double check that you’re doing this correctly in your language of choice.

If you’re trying to use a refresh token and your request looks correct, this means that the refresh token is invalid because it is expired or revoked.

Invalid code verifier

If you get an Invalid "code_verifier" error, verify that your code matches this regex pattern which is the specifications of code verifiers:

r'^[a-zA-Z0-9\-._~]{43,128}$'

Code challenge failed

If you get a Code challenge failed. error for an/oauth/token request, this means that when we S256 hash the code_verifier it does not match the code_challenge that your app initially provided during the authorization request.

Please double-check that you're sending the correct code verifier and hashing your code_verifier with S256.

403 HTML on /token or /revoke

If you get a 403 html error on /token or /revoke:

Verify that you’re making your request to the correct URL:
- https://a.klaviyo.com/oauth/token
- https://a.klaviyo.com/oauth/revoke
Requests to directly klaviyo.com will fail.

Example error:

403 ERROR
The request could not be satisfied.
This distribution is not configured to allow the HTTP request method that was used for this request. 
The distribution supports only cachable requests.
We can't connect to the server for this app or website at this time. 
There might be too much traffic or a configuration error. Try again later, or contact the app or website owner.

Error glossary

The tables below show all potential OAuth errors and offer guidance on how to fix them.

Accessing OAuth client page

Type of error	Error message	Why and how to fix
404	This www.klaviyo.com page can’t be found.	No webpage was found for the web address: https://www.klaviyo.com/oauth/client. Your current account doesn't have permission to view this page. Only the owner, admin, or manager of beta allowlisted accounts can view this page. Make sure you are in the correct account.

User granting authorization

Error type	Error message	Why and how to fix
503	N/A	OAuth service is temporarily unavailable on Klaviyo.
403	Access to www.klaviyo.com was denied. You don't have authorization to view this page.	Make sure you are logging into an account as the owner, admin, or manager role. Only these roles can grant authorization to an app.

Call to oauth/token endpoint

Error type	Error message	Why and how to fix
400	"error":"invalid_grant"	If you are making a refresh request and you get this error, your refresh token is invalid. Your token could be invalid due to: Expiring after 90 days of no-use. Getting revoked by someone in your account. Getting revoked by Klaviyo’s internal systems for security reasons. It is a wrong or incorrect token. Your customer will need to reauthorize the integration.
400	"error":"invalid_request", "error_description":"Missing "refresh_token" in request."	Missing `refresh_token` in the request body.
400	"error":"unsupported_grant_type"	Missing or incorrect `grant_type` in the request body. For refresh flow, it should be `refresh_token`; for authorization code flow, it should be `authorization_code`. Tip: Ensure the form is `x-www-form-urlencoded`.
400	"error":"invalid_grant", "error_description":"Code challenge failed."	When we S256 hash the `code_verifier`, it does not match the `code_challenge` that your app initially provided during the authorization request. Tip: Double-check that you're sending the correct code verifier and hashing your `code_verifier` with S256.
401	"error":"invalid_client"	You must send client authentication as the basic auth header. Check that: Your client ID and client secret are correct. You converted the base64 encoded credentials back to a string when concatenating with `Basic`. (In some languages, the encoding creates bytes or some other format.) The authorization header on your request is correct. Example: `Authorization: Basic <base64 encoded client_id:client_secret>`.
429	“error”:”rate_limit_exceeded”, ”error_description”:”Rate limit exceeded for refresh token. Please try again after 1 minute.”	Rate limit exceeded for OAuth refresh token. A refresh token can be used 10 times per minute maximum.
4xx	Invalid "code_verifier"	This is for the authorization code flow. The code verifier does not match with the hashed verifier code that was sent earlier.
503	N/A	OAuth service is temporarily unavailable on Klaviyo.

Error descriptions for invalid refresh token

Here are the possible error_description messages you may get when a refresh token is invalid and the reasons for them:

Error description	Why and how to fix
`"error_description": "Refresh token has been revoked"`	This is likely the only reason you will be getting an `"invalid_grant"` in production. This will occur for one of two reasons: The customer uninstalled your app in Klaviyo. Your app made a request to `/oauth/revoke` resulting in the app being revoked. This was likely because the customer uninstalled the app on your end.
`"error_description": "Refresh token does not exist"`	This refresh token does not exist. Check for typos when copying your refresh token. If you are getting this error in production, check that you aren’t truncating your tokens and that you're using the exact same value that was sent to you in the API.
`"error_description": "Refresh token expired due to inactivity"`	This is because the refresh token was not used for more than 90 days. This means that the app was inactive for 90 days for this customer, since the refresh token is used frequently to refresh access tokens.

Call to oauth/revoke endpoint

The following are errors specific to the OAuth handshake.

Error type	Error message	Why and how to fix
400	"error": "invalid_client"	You must send client authentication as the basic auth header. Check that: Your client ID and client secret are correct. You converted the base64 encoded credentials back to a string when concatenating with `Basic`. (In some languages, the encoding creates bytes or some other format.) The authorization header on your request is correct. Example: `Authorization: Basic <base64 encoded client_id:client_secret>`.
400	"error":"invalid_request"	Make sure the request content-type is `x-www-form-urlencoded`. If it is, the token is missing in the request body.
503	N/A	OAuth service is temporarily unavailable on Klaviyo.

General API call errors

The following are general API errors that occur based on how the Authorization header is passed.

Error type	Error message	Why and how to fix
401	`authentication_failed` - Incorrect authentication credentials.	Access token is invalid. It either doesn't exist, is expired, or was revoked. Please obtain a new valid access token using the refresh token.
401	`not_authenticated` - Authentication credentials were not provided.	The authorization header for OAuth is formatted incorrectly. It is most likely due to missing or extra characters in the access token, missing `Bearer` prefix, and other format-related issues with the authorization header.
503	N/A	OAuth service is temporarily unavailable on Klaviyo.