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
| Status | Meaning |
|---|---|
| 200, 201 | It worked. 201 when something was made. |
| 400 | The request is not valid: see code and details. |
| 401 | No credential, or one that is not valid. |
| 402 | The plan does not include this, a plan limit is reached, or credits are needed. |
| 403 | The credential may not do this. |
| 404 | No such endpoint, or nothing the credential may see. |
| 405 | The path does not take this method. |
| 409 | The request conflicts with the current state. |
| 410 | It existed, but is gone or has expired. |
| 413 | The body is too large. |
| 415 | The body is not the content type the endpoint takes. |
| 422 | The request is well formed but cannot be carried out on this content. |
| 429 | Too many requests: wait Retry-After seconds. |
| 500, 502, 503 | A 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.
| Status | Code | When |
|---|---|---|
| 400 | invalid_request | The path, query or body does not match the route's schema. details.issues lists each problem as { path, message }, such as body.title. |
| 400 | invalid_json | The body is not JSON. |
| 400 | invalid | A value passed the schema but cannot be used. The message says why. |
| 400 | invalid_idempotency_key | The Idempotency-Key header is not 1 to 255 visible ASCII characters. |
| 401 | unauthenticated | No bearer token, or one that is not valid, was revoked or has expired. The response carries WWW-Authenticate. |
| 402 | plan_required | The 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. |
| 402 | credits_required | The 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. |
| 403 | forbidden | The credential lacks a scope the route needs (details.missing lists them), or the member may see the resource but not change it. |
| 403 | bad_origin | A browser sent the request from an origin that may not call the API. |
| 403 | key_owner_deactivated | The member who made the API key is deactivated. The key works again if they are reactivated. |
| 403 | key_owner_removed | The member who made the API key has left the workspace. Make a new key. |
| 403 | oauth_owner_deactivated | The member who approved the OAuth client is deactivated. |
| 403 | oauth_owner_removed | The member who approved the OAuth client has left the workspace. |
| 404 | not_found | There is no such endpoint, or no such resource that the credential's member may see. |
| 405 | method_not_allowed | The path exists but not with this method. Allow lists the methods it takes. |
| 409 | conflict | The 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. |
| 409 | idempotency_key_reused | The Idempotency-Key was used for a different request. Use a new key. |
| 409 | idempotency_in_progress | A request with this Idempotency-Key is still running. Retry after Retry-After seconds. |
| 413 | too_large | The body is larger than the route accepts. |
| 415 | unsupported_media_type | The Content-Type is not the one the route takes: application/json, or application/octet-stream for raw bytes. |
| 429 | rate_limited | Too 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. |
| 500 | internal | Something went wrong on Flipbird's side. Every error response carries X-Request-Id; quote it to support. |
| 501 | not_implemented | The endpoint is declared but not available yet. |
Rate limits
| Limit | Requests a minute |
|---|---|
| Each API key or OAuth grant | 600 |
| Each workspace, across all its credentials | 1,800 |
| Each client address | 1,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_progresswithRetry-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
POSTreturns 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-Afterseconds, 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_progressorstale, andnot_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.