Troubleshoot API integrations

Use the JSON error.code and request_id. Do not diagnose by repeatedly sending the same failing request or by exposing the credential.

1. Send a small GET /school request.
2. On 401 invalid_api_key, verify the secret source, expiration, and revocation; rotate if uncertain.
3. On 403 insufficient_scope, compare error.details.required_scope with the key inventory.
4. Check separate read/write rollout, feature, suspension, policy, and source-network conditions.
5. Never solve a missing scope by reusing a broader unrelated key.

• Use only documented filter names and enum values.
• Send valid UUID and RFC 3339 UTC values.
• Do not combine created_after and updated_after.
• Keep a cursor on the same endpoint, path identifier, and normalized filters.
• On an invalid or expired traversal, restart from a new first request; never edit the cursor.

• 415: send application/json.
• 413: keep the body at or below 1 MiB.
• 422: correct the exact schema or business rule.
• 409 idempotency_key_conflict: the value was used for a different request; do not mutate the old request to fit it.
• 409 idempotency_request_in_progress: wait for Retry-After and send the identical request and key.
• API Learning Plans are read-only in v1.

For 429, respect Retry-After and the rate-limit reset. Reduce polling, increase page size within the limit, and use incremental synchronization. For 503, use bounded backoff; a required policy, quota, or API dependency can be temporarily unavailable.

Provide:

• UTC timestamp;
• HTTP method and endpoint template, without sensitive query values;
• status, error.code, and request_id;
• key name or safe identifier, not the credential;
• whether the failure is read or write and whether it is repeatable.

Never send an authorization header, raw key, raw idempotency value, full personal-data body, or unredacted logs. See errors and quotas and endpoint reference.