Getting started

Errors

Floo uses standard HTTP status codes and returns a small, predictable JSON shape so you can pattern-match on code without parsing prose.

Error shape

JSON

{
  "error": "Human-readable message describing the problem.",
  "code": "machine_readable_token"
}

error is always present; code is present on well-known failure modes (auth, billing, validation). Future fields may be added - ignore unknown keys.

Status codes

400Bad Requestinvalid_request

Required fields are missing or malformed JSON was sent. The error message names the offending field.

401Unauthorizedinvalid_api_key

API key missing, malformed, or revoked. Mint a new key from /dashboard/settings/api-keys.

402Payment Requiredinsufficient_balance

Your workspace voice balance is below the minimum needed for the requested call. Top up to retry. Response includes balance_cents and required_cents.

404Not Foundnot_found

The resource id does not exist or is owned by another workspace.

422Unprocessable Entityunprocessable

Validation passed but the request can't be fulfilled - e.g. uploading a file we can't extract text from, or starting a call on a number that isn't yours.

429Too Many Requestsrate_limited

You've exceeded the per-workspace rate limit (currently 100 req/min on writes, 600 req/min on reads). Back off and retry - the response includes a Retry-After header.

500Server Error

Something blew up on our side. Safe to retry idempotent reads; for writes, check the dashboard before re-sending to avoid duplicates.

Handling 402 (insufficient credits)

Billing failures surface as 402 with an enriched body so you can prompt the user to top up without a follow-up request.

JSON

{
  "error": "Insufficient voice balance",
  "code": "insufficient_balance",
  "balance_cents": 4,
  "required_cents": 12
}

Retry guidance

Idempotent reads (GETs): retry freely with exponential backoff.
Writes: retry on 429 and 500. For 5xx during call placement, query GET /api/v1/calls first to confirm whether the call actually started before re-sending.
4xx (except 429): don't retry. Fix the request.