API

Errors and limits

How the API says no, the codes to switch on, the rate limits, and how to retry safely.

The error body

Every error is JSON with a stable code to switch on and a message written for people, which may change. Some add details. Every error response also carries an X-Request-Id header: quote it if you contact support.

403 Forbidden

{
  "error": {
    "code": "forbidden",
    "message": "This API key cannot do that.",
    "details": {
      "missing": [
        "documents.publish"
      ]
    }
  }
}

400 Bad Request

{
  "error": {
    "code": "invalid_request",
    "message": "The body is not valid.",
    "details": {
      "issues": [
        {
          "path": "body.title",
          "message": "Too small: expected string to have >=1 characters"
        }
      ]
    }
  }
}

Status codes

StatusMeaning
200, 201It worked. 201 when something was made.
400The request is not valid: see code and details.
401No credential, or one that is not valid.
402The plan does not include this, a plan limit is reached, or credits are needed.
403The credential may not do this.
404No such endpoint, or nothing the credential may see.
405The path does not take this method.
409The request conflicts with the current state.
410It existed, but is gone or has expired.
413The body is too large.
415The body is not the content type the endpoint takes.
422The request is well formed but cannot be carried out on this content.
429Too many requests: wait Retry-After seconds.
500, 502, 503A problem on Flipbird's side or with a service it calls. Retry later.

Error codes

These can come from any endpoint. Each group in the reference lists the codes particular to its endpoints.

StatusCodeWhen
400invalid_requestThe path, query or body does not match the route's schema. details.issues lists each problem as { path, message }, such as body.title.
400invalid_jsonThe body is not JSON.
400invalidA value passed the schema but cannot be used. The message says why.
400invalid_idempotency_keyThe Idempotency-Key header is not 1 to 255 visible ASCII characters.
401unauthenticatedNo bearer token, or one that is not valid, was revoked or has expired. The response carries WWW-Authenticate.
402plan_requiredThe workspace's plan does not include API access or the route's feature, or a plan limit (seats, published documents, storage) is reached. details, when present, gives the reason (feature or limit), the feature, and requiredPlan, the least plan that allows it.
402credits_requiredThe work is metered, and metered work is paused because the workspace's balance is overdrawn past its throttle mark. details gives the work and the credit standing. Adding credits lifts it.
403forbiddenThe credential lacks a scope the route needs (details.missing lists them), or the member may see the resource but not change it.
403bad_originA browser sent the request from an origin that may not call the API.
403key_owner_deactivatedThe member who made the API key is deactivated. The key works again if they are reactivated.
403key_owner_removedThe member who made the API key has left the workspace. Make a new key.
403oauth_owner_deactivatedThe member who approved the OAuth client is deactivated.
403oauth_owner_removedThe member who approved the OAuth client has left the workspace.
404not_foundThere is no such endpoint, or no such resource that the credential's member may see.
405method_not_allowedThe path exists but not with this method. Allow lists the methods it takes.
409conflictThe change conflicts with what is already there, such as a name another item already has, or two requests making the same thing at the same moment.
409idempotency_key_reusedThe Idempotency-Key was used for a different request. Use a new key.
409idempotency_in_progressA request with this Idempotency-Key is still running. Retry after Retry-After seconds.
413too_largeThe body is larger than the route accepts.
415unsupported_media_typeThe Content-Type is not the one the route takes: application/json, or application/octet-stream for raw bytes.
429rate_limitedToo many requests; wait Retry-After seconds. For the request limits below, details.limit is key, tenant or address; an endpoint's own limit, such as on starting uploads, gives no details.
500internalSomething went wrong on Flipbird's side. Every error response carries X-Request-Id; quote it to support.
501not_implementedThe endpoint is declared but not available yet.

Rate limits

LimitRequests a minute
Each API key or OAuth grant600
Each workspace, across all its credentials1,800
Each client address1,200

A refusal is 429 rate_limited, with details.limit saying which limit (key, tenant or address) and Retry-After: 60. Some endpoints also have limits of their own, such as starting uploads and drawing QR codes as PNG; their 429 carries Retry-After but no details. Spread bulk work out rather than sending it in bursts, and wait as long as Retry-After says before trying again.

Idempotency

A network failure can leave you not knowing whether a request worked. Send an Idempotency-Key header with every mutation, a value unique to that operation such as a UUID, and retry with the same key: for 24 hours the API answers the same request with the first response again, marked Idempotent-Replayed: true, instead of doing it twice.

  • A key belongs to the credential that sent it. It is 1 to 255 visible ASCII characters.
  • The same key with a different method, path, query or body answers 409 idempotency_key_reused.
  • While the first request is still running, a retry answers 409 idempotency_in_progress with Retry-After: 1.
  • Only a success is kept. After an error the key is free again, so you can fix the request and send it with the same key.
  • Downloads that a POST returns ignore the key.
  • assets.upload ignores the key too: it streams its body (up to 95 MiB) rather than holding it for a replay, and an upload sent again already returns the same asset, with deduplicated: true.

Retrying

  • 429: wait Retry-After seconds, then retry.
  • 500, 502 and 503, and a request that timed out: retry with the same Idempotency-Key, backing off between attempts.
  • 409 idempotency_in_progress: retry after a second.
  • 409 locked, save_in_progress or stale, and not_ready: the state the code names has to change first, so read it again or wait, then retry.
  • 402 credits_required: retry once credits are added.
  • Any other 4xx: the same request will get the same answer. Fix the request or the credential first.