> For the complete documentation index, see [llms.txt](https://developers.felt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.felt.com/rest-api/errors-and-rate-limits.md). # Errors and rate limits Almost every error returned by the Felt API uses the same JSON envelope: an `errors` array where each entry has a `title`, a human-readable `detail`, usually a stable `code`, and — where applicable — a `source` telling you which header, parameter, or body field caused the problem. ```json { "errors": [ { "title": "Not found", "detail": "Map not found", "code": "not_found", "source": { "parameter": "map_id" } } ] } ``` Treat `code` as best-effort rather than guaranteed: a few responses — notably field-validation failures and plan-limit errors — carry only `title` and `detail`. Branch on the HTTP status first, and use `code` to refine when it is present. ## Status codes | Status | Code | Meaning | What to do | | ------ | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `401` | `unauthorized`, `invalid_access_token` | Missing, malformed, revoked, or wrong-workspace token. Requests with a valid token for a resource in a *different* workspace also return 401. **Permission failures also return 401**, not 403 — for example, editing or deleting a map your account can only view. | Check the `Authorization: Bearer` header and that the token was created in the same workspace as the resource. If the token is fine, ask a workspace admin for the required role on the resource. See [Authentication](/rest-api/authentication.md). | | `403` | `forbidden`, `over_storage_limit`, `over_processing_limit`, `unauthorized` | Your workspace has hit a plan limit — data hosting or monthly data processing — or the action requires a plan your workspace isn't on. | Read `detail`: it names the limit. Reach out to [our team](https://felt.com/sales) to raise it. | | `404` | `not_found` | The resource doesn't exist. The `source.parameter` field names the offending ID. | Verify the ID. Remember that map IDs come from the map URL, while layer IDs come from API responses. | | `422` | `invalid` | The request body or parameters failed validation. `source.pointer` identifies the invalid field. | Fix the field named in `detail` / `source` and retry. | | `429` | `too_many_requests` | You hit a rate limit (see below). | Back off and retry later. | When handling responses in code, print the error body rather than only asserting success — `detail` almost always tells you exactly what's wrong: ```python r = requests.post(url, headers=headers, json=body) if not r.ok: print(r.status_code, r.json()["errors"]) r.raise_for_status() ``` ## Rate limits Two independent limits apply: 1. **Per-IP request throttle** — currently 300 requests per minute per IP address. Exceeding it returns `429` with the `too_many_requests` code above. Spread bulk work out or batch it (for example, upsert many annotations in one `POST /elements` call instead of one call per feature). 2. **Plan usage limits** — depending on your plan, API usage may also be subject to an overall usage limit. Every API response includes an `x-api-limit-exceeded` header (`true` or `false`); if your workspace exceeds its limit, requests return `429`. Reach out to [our team](https://felt.com/sales) if you have questions about your plan's API access. When you receive a `429`, retry with exponential backoff and jitter rather than immediately — and check `x-api-limit-exceeded` to distinguish the per-IP throttle (`false`) from a plan usage limit (`true`). ## Pagination List endpoints (`GET /projects`, `GET /library`, `GET /maps/{map_id}/elements`, and so on) currently return **all** results in a single response — there are no pagination parameters. For very large maps, prefer scoping your reads (for example, listing a single element group) over repeatedly fetching full collections. ## Versioning The current API version is `v2`, served under `https://felt.com/api/v2`. The machine-readable OpenAPI spec for the exact version in production is always available at: ``` GET https://felt.com/api/v2/openapi.json ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers.felt.com/rest-api/errors-and-rate-limits.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.