Errors and limits
Diagnose failed authorization, handle rate limits, and reconnect safely.
Library errors
Check the HTTP status before reading a success response. Application errors may include error and message; framework errors may instead include statusCode, error, and message. Do not depend on the wording of a message.
| HTTP status | Meaning | Action |
|---|---|---|
| 400 | Invalid filters, cursor, or extra query parameters | Correct the request; do not retry unchanged. |
| 401 | Missing, expired, or revoked access token | Refresh once if eligible, otherwise reconnect. |
| 403 | Missing permission, ineligible account/app, or unregistered browser origin | Check scope, review status, account eligibility, and callback origins. |
| 404 | Integrations unavailable on the deployment | Check availability; documentation alone does not enable access. |
| 429 | Rate limit reached | Respect Retry-After and back off. |
| 503 | Temporarily unavailable, including authentication maintenance | Retry later with backoff; honor Retry-After when present. |
Never try another user's ID to resolve an authorization failure. The library endpoint accepts only the user represented by the validated token.
Rate limits
Library reads are limited to 60 requests per minute per app/user, 1,000 per minute per app, and 120 per minute per network address at the route layer. Shared backend addresses can reach the network limit before the app limit.
Use larger pages, spread synchronization jobs out, and stop polling disconnected accounts. Respect Retry-After when available; browser CORS may not expose every response header, so use a conservative 60-second delay if a 429 has no readable retry value. Add jitter and cap repeated retries.
Do not publicly cache delegated library responses. Responses carry Cache-Control: private, no-store.
OAuth errors
OAuth endpoints return protocol errors, commonly error with error_description. Some validation failures use message instead. User denial can be returned to your callback as access_denied; validate state even for error callbacks.
- Invalid callback: use the exact approved URL. A callback added to a pending revision is not active yet.
- PKCE failure: keep the original verifier; send the base64url SHA-256 challenge with
S256. Do not regenerate the verifier on callback. - Invalid client: check the client type and HTTP Basic credentials. A rotated secret replaces the old one immediately.
- Invalid grant: the code/token may be consumed, expired, revoked, or bound to a session that ended. Start a new authorization attempt.
- Invalid scope or resource: request
library:read, optionallyoffline_access, and the exact resourcehttps://api.comick.dev/integrations/v1. - Other users cannot connect: new draft, pending, or rejected apps can test only with their owner until approval.
- Browser CORS failure: use a public browser client, a registered HTTP(S) callback origin, and requests without cookies.
Contact support
Contact [email protected] with the client ID, endpoint, HTTP status, time, and a sanitized description. Never send client secrets, tokens, authorization codes, PKCE verifiers, or complete callback URLs containing credentials.