API requests return permission, validation, or rate-limit errors

SymptomCopy link to Symptom

Authentication succeeds, but API v2 returns 403, a validation error, 404, 409, or 429 rate_limit_exceeded.

Most likely causesCopy link to Most likely causes

• The key lacks the endpoint’s required scope (insufficient_scope).
• The community plan, trial, subscription, or feature state blocks the operation.
• A path, query, or JSON field has the wrong type, value, or constraint.
• The resource does not exist in this community.
• Current state conflicts with the requested change.
• The integration exceeded the current rate limit.

Diagnostic checksCopy link to Diagnostic checks

1. Record the method, /v2 path, status, and complete error object.
2. Compare the endpoint’s Required scope and feature in the API reference.
3. Validate required fields, allowed enum values, numeric bounds, and content type.
4. Confirm all IDs belong to the authenticated community.
5. For 429, read Retry-After and error details such as limit, remaining, and resetMs when supplied.
6. For a write timeout or conflict, fetch current state before another attempt.

ResolutionCopy link to Resolution

Grant only the missing scope, restore the entitled feature, or correct the request to match the generated schema. Respect Retry-After with bounded backoff and reduce unnecessary polling. Do not hard-code a universal request quota because limits can vary by deployment.

When to retryCopy link to When to retry

Retry a corrected validation request immediately. Retry 429 only after Retry-After. Safe reads can be retried with backoff; retry writes only when the endpoint documents idempotent behaviour or after reconciling state.

Contact supportCopy link to Contact support

Contact Clan Labs support for a reproducible request that matches the current reference but returns an unexplained server or permission error.

Include this informationCopy link to Include this information

Include request method/path, redacted body, status, response error object, response/request correlation header if present, timestamp, key name and scopes, and plan. Never include the API key.