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.

{
  "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.
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 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:

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 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