Rate limits and errors
How many requests iyedy's API and MCP server accept per minute, the headers that tell you where you stand, and every error code with what to do.
On this page
| Who | Sustained | Burst |
|---|---|---|
| A person on Free | 60 a minute | 180 |
| A person on a paid plan | 120 a minute | 360 |
| A Team organisation, all its members together | 3,000 a minute |
The limits are counted per person, on every API request with a token or a session, and on MCP calls. In a Team organisation, the organisation's limit also applies to its members' requests. A single diagram accepts up to 10 writes a second.
Know where you stand
Every answer carries two headers:
RateLimit-Policy: the limit that applies to you;RateLimit: what is left in the current window.
When you go over, the answer is 429 with the code rate_limited, the name of the limit in detail.bucket, and a Retry-After header in seconds. Wait that long, then retry once. Retry only requests that are safe to repeat: reads, and creating requests sent with an Idempotency-Key.
Sizes
| What | Most |
|---|---|
| A request body | 300 KiB |
| A diagram's definition sent to replace it | 1 MiB |
| A definition sent to MCP for a preview or a proposal | 1 MiB |
| An MCP tool answer | 100,000 characters of JSON |
The shape of an error
Every error is a JSON object:
{
"error": {
"code": "permission_denied",
"message": "…",
"detail": { "reason": "insufficient_scope", "required": "cartouche.propose" },
"requestId": "req_7f3c2a90-5b1e-4c8d-9a61-0e2b4d6f8a13"
}
}
Give the requestId to support when you ask about an error. The message is for people; your code should test code and detail.reason.
Error codes
| HTTP | code |
Meaning | What to do |
|---|---|---|---|
| 400 | invalid_argument |
A parameter or the body is not what the route expects | Check the request against the OpenAPI document |
| 401 | unauthenticated |
No valid token; detail.reason says why |
See 401 reasons |
| 402 | plan_limit |
A limit of your plan is reached; detail.reason names it |
See Plan limits |
| 403 | permission_denied |
Your role, the route or a scope does not allow this | See 403 reasons |
| 403 | read_only |
The diagram is read-only for now | detail.reason says why: plan limit, lapsed plan, legal hold |
| 404 | not_found |
It does not exist, or you may not read it | Check the ids; a read you are not allowed looks the same |
| 409 | conflict |
The diagram moved on since the version you sent | Read it again, then retry from the new version |
| 409 | already_issued |
A request that issues a secret was replayed | Revoke what was issued and ask again |
| 413 | too_large |
The body is over the size limit | Send less |
| 422 | validation_failed |
The content is not valid; nothing was saved | Read detail for the diagnostics |
| 423 | legal_hold |
A legal hold keeps the diagram as it is | Nothing to do from the API |
| 429 | rate_limited |
Too many requests | Wait for Retry-After, then retry once |
| 5xx | unavailable |
iyedy could not answer | Retry later |
401 reasons
detail.reason |
Meaning |
|---|---|
invalid_token |
The token is malformed or unknown |
token_expired |
The token is past its lifetime |
token_revoked |
The token was revoked |
ip_not_allowed |
A service-account token used from outside its allowed addresses |
pats_disabled |
The organisation does not allow personal access tokens |
403 reasons
detail.reason |
Meaning |
|---|---|
insufficient_scope |
The token lacks the scope named in required |
token_not_accepted |
The route is not part of the public API: tokens cannot call it |
mcp_disabled |
The organisation has MCP clients turned off |
Address not allowed
A service-account token sent from an address outside the ones allowed for that service account is refused. The answer is 401 with unauthenticated and detail.reason ip_not_allowed, like the other token refusals above. Send the request from an allowed address. See Service accounts.
Too many requests
The answer is 429 with the code rate_limited, the name of the limit in detail.bucket, and a Retry-After header in seconds. Wait that long, then retry once, and only a request that is safe to repeat. See Know where you stand and the limits at the top of this page.
Errors of the MCP server
Claude's MCP endpoint answers 401 when the sign-in is missing or expired, so that Claude signs you in again, and 403 with insufficient_scope when a tool needs a permission you did not approve. If iyedy's sign-in cannot be reached, it answers 503 with Retry-After: 5. Refusals inside a tool (no iyedy account yet, MCP off for the organisation, a client not allowed, single sign-on required) come back as a tool error that says what to do: see Claude troubleshooting.
Was this page helpful?Your answer is anonymous and counts only if you accepted measurement.
What went wrong?
Don't write personal data.