Errors, limits and revocation

Status codes

Code	Meaning	What to do
401	No token, an expired one, or a revoked grant	Read WWW-Authenticate. Refresh, or send the person through consent again
403	Authenticated, but not allowed — a missing scope, an unpaid plan, or a banned account	Do not retry. Ask for the scope you need, or tell the person their plan does not cover this
409	An Idempotency-Key reused with a different body	Use a new key
429	Rate limited	Wait for Retry-After
202	Accepted, not finished	Poll

A 401 and a 403 mean genuinely different things here and are worth handling apart. 401 is recoverable by you. 403 usually needs the person to do something.

Rate limits

Every response carries:

RateLimit-Limit: 30
RateLimit-Remaining: 28
RateLimit-Reset: 59

Read them rather than guessing a safe rate. Anonymous and authenticated callers have different budgets, and they are not documented as fixed numbers here because they move.

Revocation takes effect immediately

The person can disconnect your client from their settings at any time. When they do:

• your still-valid access token stops working on the next request — every route, both MCP and REST, answers 401
• your refresh token stops working too — invalid_grant

This is not a token-expiry delay. The grant is checked per request, deliberately, because somebody pressing disconnect because they think a credential leaked does not mean in fifteen minutes.

There is no way to detect this in advance and no way to undo it. Treat a sudden 401 on a token you believe is fresh as “the person disconnected me”, stop retrying, and if you need access again, send them through consent.

Being a good citizen

• Ask for the scopes you need, not all nine. The consent screen lists every one, and a request for the lot reads as one
• Use Idempotency-Key on ask if you might retry. Without it a retry is a second charge
• Do not poll tightly. Ingest takes as long as it takes
• Do not treat 202 as done

When a page here is wrong

The service is authoritative. If this handbook disagrees with what https://api.uely.ch/openapi.json or a live response tells you, believe the service — and please say so, because it means this page needs fixing.