API Authentication Errors

What This Guide Covers

Authentication errors are the most common reason an integration stops working. Most of the time, the fix is straightforward once you know what the error actually means.

This guide covers the errors we see most often and how to resolve them.

The Most Common Auth Errors

401 Unauthorized

This means the API rejected your credentials entirely. The token or API key you sent is either invalid, expired, or missing.

Common causes:

• The access token expired and wasn’t refreshed
• The token was revoked or regenerated in the platform settings
• The Authorization header is malformed or missing
• You’re hitting the wrong environment (sandbox token against production, or vice versa)

What to do: Check that the token is still active in the platform’s settings. If it’s an OAuth token, check whether the refresh token is still valid. If the token was regenerated, send us the new one through our secure credential link.

403 Forbidden

Your credentials are valid, but you don’t have permission to do what you’re trying to do.

Common causes:

• The API key or app doesn’t have the right scopes enabled
• Your account plan doesn’t include API access to that feature
• The resource belongs to another user or team and your permissions are restricted

What to do: Check the scopes or permissions assigned to your API key or private app. Compare them against what we documented during setup. If a scope is missing, add it — you usually don’t need to regenerate the token.

Token Expired

OAuth tokens have a limited lifespan, often 30 minutes to a few hours. When they expire, the integration needs to use a refresh token to get a new one.

When refresh fails:

• The refresh token itself has expired (some platforms expire these after 6 months of inactivity)
• The user revoked the app’s authorization
• The OAuth app was deleted or reconfigured
• The platform changed their OAuth flow and the old refresh token format is no longer accepted

What to do: If the refresh token is dead, someone with admin access needs to re-authorize the app. We’ll walk you through it.

Invalid Scope

The token is valid and not expired, but it’s trying to access a resource it wasn’t granted access to.

Example: Your HubSpot private app has read access to contacts but not write access, and the integration tries to create a contact.

What to do: Edit the app’s permissions to add the missing scope. In most platforms, the existing token picks up new scopes without needing to be regenerated.

OAuth vs API Key — Different Failure Modes

API keys are simpler. They don’t expire on a timer (usually), but they can be revoked or regenerated. If an API key stops working, someone changed it on the platform side.

OAuth tokens are more complex. They involve access tokens, refresh tokens, authorization flows, and scopes. More moving parts means more ways things can break — but OAuth also gives you more granular control over what the integration can access.

Most of the “it randomly stopped working” issues we see are OAuth refresh failures. API key integrations tend to either work or not.

When to Regenerate vs Fix the Request

Regenerate credentials when:

• The token was compromised or shared insecurely
• You see 401 errors and the token looks correct
• The refresh token chain is broken and re-auth is needed
• The platform required a migration to a new auth method

Fix the request when:

• You see 403 errors (it’s a permissions problem, not a credentials problem)
• The error message mentions a specific scope
• The same credentials work for some endpoints but not others

Common Issues

“It Was Working Yesterday”

The most common cause is an expired OAuth token where the refresh also failed silently. Check the platform’s connected apps or authorized integrations list to confirm the connection is still active.

Multiple Environments

If you have both a sandbox and production account, make sure the credentials match the environment. A production token won’t work against a sandbox URL.

Rate Limiting vs Auth Errors

Some platforms return a 401 or 403 when you’ve hit a rate limit, instead of the expected 429. If you see intermittent auth errors that resolve on their own, rate limiting may be the actual cause.

Next Steps

• If you’re seeing webhook-specific errors, read Common Webhook Issues
• New to APIs? Start with What Is an API
• Learn more about our API Integration Services