Help CenterDevelopers & APIFix a problem
Fix integration, API and Webhook errors
Every error response your integration might get, with its reason and its fix: authentication, scopes, rate, OAuth and Webhooks.
If something goes wrong
What you see
Why
What to do
401 Missing API key / Missing access tokenThere’s no token in the request.
Send
X-Api-Key or Authorization: Bearer.401 Invalid or expired API keyThe key is revoked, expired or wrong.
Treat it as a disconnect and ask for a new key. See Create and revoke an API key.
401 Invalid or revoked access tokenThe OAuth token was revoked.
Run the OAuth flow again.
401 Access token expiredThe token’s hour is up.
Refresh with
refresh_token.401 Token is not bound to a workspaceA damaged token.
Issue a new token.
403 on a records endpointA scope is missing (
INSUFFICIENT_SCOPE, with required_scope).Create a key with the scope. See Key scopes, and how they combine with permissions.
403 RESOURCE_FORBIDDENThe member or the record is outside the permissions.
Raise the permission of the key’s creator.
403 You cannot grant scopes you don’t holdYou’re granting a scope you don’t have.
Choose fewer scopes.
403 on managing subscriptionsThe request used a user session, or has no
read.Use a key with the read scope.
429 API key rate limit exceededYou went over 120 requests a minute.
Slow down and batch the requests.
400 on a writeA field name instead of its ID, or a value that isn’t valid.
Use field IDs. See Records, comments and field discovery endpoints.
200 with an ASSIGN_SCOPE_DENIED noticeThe assignee change was dropped.
Add the
assign scope.Fewer records than expected
The creator’s level limits what they see.
Create the key from a member with a higher level.
invalid_grant: code is invalid, expired, or already usedThe authorization code is old.
Exchange it within 60 seconds.
invalid_grant: redirect_uri mismatchA different URI.
Match the URI exactly.
invalid_grant: PKCE required for public clients / PKCE verification failedPKCE is missing or wrong.
Send
code_challenge, then the matching code_verifier.invalid_client: bad client secretA wrong secret.
Use the right secret.
invalid_grant: refresh tokenThe refresh token was already used, or has expired.
Connect again. Never use an old refresh token.
A Webhook doesn’t arrive
The URL isn’t HTTPS, the reply isn’t
2xx, or the change came from your own key.The signature doesn’t match
The body was re-serialized.
Verify on the raw body. See Verify a Webhook signature and prevent duplicates.
A duplicate event
A retry.
Prevent duplicates with the delivery ID.
Did this guide solve it?
If not, we’ll ask what was missing.