Errors and limits
What each API and MCP error means, how to fix it, and the rate and size limits.
API errors
The API returns errors in the GraphQL errors array. Each has a message and an extensions.code:
{
"errors": [
{
"message": "Missing permission atlas.view",
"extensions": { "code": "MISSING_PERMISSION", "http": 403, "key": "atlas.view", "requestId": "…" }
}
],
"data": null
}| Code | Meaning | What to do |
|---|---|---|
UNAUTHENTICATED | No key, or the key is wrong, expired, or revoked, or its creator is no longer active. Also returned by parts of OpsLyft that don't accept keys yet. | Check the Authorization: Bearer header. Create a new key if it has ended. |
MISSING_PERMISSION | The key's role doesn't include the permission in extensions.key. | Create a key with a role that has it. Viewer covers every read. |
MODULE_NOT_ENABLED | Your organisation hasn't turned that module on. | Ask an Owner or Admin. |
FORBIDDEN | The key isn't allowed to do this at all, for example managing people or keys. | Do it in the app, signed in. |
NOT_FOUND | The item doesn't exist, or it's outside the key's scope. | Check the id, and the key's scope. |
INVALID_INPUT | The query or its arguments aren't valid. The message says what's wrong. | Fix the request. |
CONFLICT | The item changed since you read it. | Read it again and retry. |
TIMEOUT | The query took too long. | Narrow the date range or group by less, then retry. |
CLICKHOUSE_UNAVAILABLE, DEPENDENCY_UNAVAILABLE | A service OpsLyft depends on is briefly unavailable. | Retry after a short wait. |
INTERNAL | Something went wrong on OpsLyft's side. | Retry. If it keeps happening, contact support with the requestId. |
Include extensions.requestId when you contact support. It lets us find your request.
MCP errors
Connection errors
| Status | Body | What to do |
|---|---|---|
401 | {"error":"Unauthorized"} | The key is missing, wrong, expired, or revoked, or its creator is no longer active. Check the X-Opslyft-Key header, or create a new key. |
429 | {"error":"Rate limit exceeded","retry_after_seconds":12} | Wait that many seconds, then reconnect. |
404 | {"error":"Session not found"} | The session ended, often because of an OpsLyft release. Reconnect. |
Tool errors
A tool that fails still returns a normal result. The JSON inside it has "error": true:
{ "error": true, "code": "UNAUTHORIZED", "message": "Missing permission atlas.view", "missing_permission": "atlas.view" }| Code | Meaning |
|---|---|
UNAUTHORIZED | The key lacks the permission, the module is off, or the key has no access in this organisation. The message says which. |
INVALID_INPUT | An input is missing or wrong. The message lists valid values where it can, for example the dimensions you can use. |
NOT_FOUND | No item with that id is visible to the key. |
QUERY_TOO_LARGE | The date range is longer than 366 days. |
INTERNAL_ERROR | Something went wrong on OpsLyft's side. Retry. |
AI clients read these messages and usually correct themselves.
Rate limits
API
There's no fixed request limit on the API today. Large cost queries are limited by time instead: OpsLyft stops a query after about two minutes. Keep requests reasonable, and cache results you reuse. Limits may be added later, with notice.
MCP
MCP counts requests in one-minute windows, per key and across your organisation.
| Limit | Per minute |
|---|---|
Organisation and identity tools (get-customer-info, get-user-profile, get-currency-in-use, get-rca-hierarchy) | 120 per key |
| Allocation edit tools | 10 per key |
| Every other tool, and new connections | 60 per key |
| Everything, across all keys in your organisation | 300 |
start-session and end-session don't count.
When you're over a limit, you get 429 with a Retry-After header saying how many seconds to wait. Responses also carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (a Unix time).
Other limits
| Limit | Value |
|---|---|
| Request body | 10 MB |
| API query time | About 2 minutes |
| Date range in an MCP cost tool | 366 days |
Rows per costQuery page | 1,000 by default |
| Key lifetime | Up to 1 year |
| Allocation file import (MCP) | 6 MB |