Troubleshooting & FAQ ​

Rows list a symptom, its cause, and a fix. Check the provider label, then find your symptom under a heading.

401 Unauthorized ​

AniList. The token is missing, expired, or revoked. Mutations and viewer-scoped queries require a token. Public queries do not. Configure refreshToken, clientId, and clientSecret. AniLink refreshes automatically after a 401 and replays the request once. See automatic refresh. Otherwise, re-run the OAuth flow and create a new client with the fresh token. See the token-refresh recipe.

MAL. MAL access tokens expire by design. Configure refreshToken and clientId. AniLink refreshes automatically after a 401 and replays the request once. See automatic refresh. Otherwise, call refreshMalAccessToken before the token expires. See the token-refresh recipe.

429 Too Many Requests ​

Both providers enforce rate limits. By default, AniLink retries 429 responses with backoff and honors Retry-After. If 429 responses continue:

• You disabled retries (retry: false). Re-enable them, or catch AniLinkApiError and check error.rateLimit?.reset.
• You send more requests than the rate limit allows. Enable paceWithRateLimit so the client waits before it reaches the limit.

Timeouts ​

TIMEOUT_ERROR means the request exceeded its timeout (30000 ms by default). Increase the timeout for slow endpoints or set it per request. Setting it to 0 disables the timeout, so a stalled request can wait indefinitely.

Invalid fields (MAL) ​

MAL returns 400 if fields contains an unsupported name. Check valid names in the MAL API v2 schema. AniLink passes fields through unchanged.

Missing provider credentials ​

AniLinkAuthError before a request is sent means the operation requires a token that's missing from its provider configuration. For example, mal.user.me() requires mal.accessToken, and AniList mutations require authToken. Add the token to the correct provider slot.

Unexpected GraphQL envelope ​

anilist.custom() unwraps single-root-field documents to the bare value and returns the full { data } envelope for multi-root documents. If the result has an unexpected shape, count the document's root fields. See Custom queries.

FAQ ​

Does one client share tokens between providers? No. Each provider has its own credential slots. See Provider configuration.

Does AniLink retry mutations? Not by default. You can opt in explicitly. See Retries & resilience.

Does AniLink normalize AniList and MAL data? No. Map the data in your application.

Where are exact types documented? The TypeDoc API reference. The operation reference links each operation to its TypeDoc page.