Troubleshooting
Common errors and how to resolve them.
401 Unauthorized
The API-Key is missing, wrong, or doesn't match the environment you're targeting. Check the
authentication header and that the key belongs to the right
environment.
403 Forbidden on an action
A policy denied the call, or default-deny on writes blocked a write with no allowing policy. Use the dry-run check to see which policy applies:
A 403 on an approval means separation of duties blocked a self-approval.
202 Accepted instead of a result
The action needs approval. It's held with an approval_id until a different person
approves it; it hasn't run yet.
404 on a connection
Either the connection doesn't exist, or it belongs to a different environment —
cross-environment lookups return 404 by design. Confirm provider_config_key and connection_id, and
that you're using the matching key.
Connection status is expired or error
The stored credentials are no longer valid. Re-run the connect flow or
update the credentials. Use the /test endpoint to check health.
429 Too Many Requests
You've hit a monthly quota. Honor the Retry-After header; check the
X-RateLimit-* headers for remaining headroom.
A webhook isn't arriving
Verify the subscription matches the event type and provider, that the inbound
signature verifies, and inspect the event's status (it may be in
dead_letter after failed forwarding).