> 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, 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. A feature your plan doesn't include also returns 401, with a `detail` such as "Your plan doesn't support…" or "…need the Platform add-on". | 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. If `detail` names a plan or add-on, see [Plans, access and limits](/plans-access-and-limits.md). | | `403` | `forbidden`, `over_storage_limit`, `over_processing_limit`, `over_data_connection_limit`, `unauthorized` | Your workspace has hit a usage limit (storage, monthly processing, or data connections), or a feature such as layer components or data export isn't on your plan. | Read `detail`: it names the limit. Add capacity or upgrade from your workspace's billing settings; see [Plans, access and limits](/plans-access-and-limits.md). | | `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 the per-IP request throttle. See below. | Back off and retry. | 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 Each IP address can make 300 requests per minute. Exceeding it returns `429` with the `too_many_requests` code. Retry with exponential backoff and jitter, and spread bulk work out or batch it (for example, upsert many annotations in one `POST /elements` call instead of one call per feature). ## 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` 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 what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.