Error Reference

Error responses

Status	Error	Meaning
`400`	`invalid_request`	Missing or malformed parameter
`401`	`invalid_grant`	Code expired/used, redirect_uri mismatch, PKCE verification failed, or refresh token revoked
`401`	`invalid_token`	Access or installation token expired or wrong type
`403`	`missing_scope`	Token is valid but the route needs a scope you don't hold
`403`	`wrong_organization`	Token's grant org doesn't match the resource's org
`404`	`grant_not_found`	The `grantId` was deleted or never existed
`410`	`grant_revoked`	Grant exists but was revoked by the user or partner
`429`	`rate_limited`	Per-installation rate cap hit (1,000 req/min default)

Error body format

All errors return a JSON body:

{
  "error": "missing_scope",
  "required": "translations:publish"
}

The required field is only present for missing_scope errors.

How to handle each error

`401 invalid_grant`

One of:

The authorization code expired (default 10 minutes) or was already exchanged
redirect_uri doesn't byte-for-byte match what you sent in step 1 of the authorize flow
PKCE code_verifier doesn't match the code_challenge you sent in step 1
The refresh token was revoked

Stop retrying. For an expired code, restart the authorize flow. For a refresh-token revoke, mark the connection dead and surface a "Reconnect" prompt.

`401 invalid_token`

Your access or installation token expired. Refresh the access token, then re-mint the installation token. If refresh also fails with invalid_grant, the user revoked.

`403 missing_scope`

Your token doesn't have permission for this endpoint. Do not retry. The user needs to re-authorize with a wider scope set. Surface the missing scope to the user.

`410 grant_revoked`

The grant was explicitly revoked. Mark the connection as dead in your database and show a reconnect prompt. The user must go through the full OAuth flow again.

`429 rate_limited`

Back off and retry after the Retry-After header value. Default rate limit is 1,000 requests per minute per installation token.

On this page