Skip to content
Floweet
Pro access

Errors and error codes

One error shape { error: { code, message, details } }, the table of every code with its HTTP status, and when to retry a request.

api.floweet.com/v1 · Contract 1.0.0-beta.1 · Beta

Sections · Errors
On this page
  1. Example: invalid request
  2. The 23 codes
  3. What the details carry
  4. Retrying safely

Every error returns a 4xx or 5xx status and the same JSON body, whatever the operation: a stable code, to test in your code; a message for a human, in the Accept-Language language (en, fr, es, it, de, pt), which may change; sometimes details.

Error body
{
  "error": {
    "code": "string",
    "message": "string",
    "details": "(optional)"
  }
}

Example: invalid request

Response 400
{
  "error": {
    "code": "validation_error",
    "message": "Some fields are invalid. Please check your input.",
    "details": {
      "target": "query",
      "issues": [
        {
          "path": "department",
          "message": "Invalid string: must match pattern /^(\\d{2}|2[AB])$/i"
        }
      ]
    }
  }
}

details.target says where the problem is (json for the body, query, param for the path); details.issues lists each problem, with path (the field) and message.

The 23 codes

HTTPCodeMeaningWhat to do
400validation_errorSome fields are invalid. Please check your input.Fix the request; do not retry it unchanged
400bad_requestYour request is incomplete or malformed.Fix the request; do not retry it unchanged
400invalid_cursorThis pagination cursor is invalid. Start the list again without “cursor”.Start the list again from the first page
401invalid_api_keyMissing or invalid API key. Add the header “Authorization: Bearer fw_live_…”.Fix the request; do not retry it unchanged
401api_key_revokedThis API key has been revoked. Ask contact@floweet.com for a new key.Write to us (key, scopes, API account)
403insufficient_scopeThis API key does not have the scope required by this route.Write to us (key, scopes, API account)
403live_not_enabledProduction is not enabled for this account yet: use an fw_test_ key or ask contact@floweet.com to enable it.Write to us (key, scopes, API account)
403account_suspendedAPI access is suspended for this account. Write to contact@floweet.com.Write to us (key, scopes, API account)
403account_misconfiguredThis organization's API account is misconfigured (designated member missing). Write to contact@floweet.com.Write to us (key, scopes, API account)
403plan_requiredThis module is not included in your organization's plan.The module is not in the organization's plan: change plans
404not_foundThis resource could not be found.Fix the request; do not retry it unchanged
404sirene_not_foundEstablishment not found in the SIRENE directory.Fix the request; do not retry it unchanged
409idempotency_in_progressA request with the same idempotency key is in progress. Retry in a moment.Retry after Retry-After (or a few seconds)
422idempotency_key_mismatchThis idempotency key was already used for a different request (method, path or body). Use a new key.Fix the request; do not retry it unchanged
422prospect_limitYou have reached the limit of 200 prospects. Delete some before adding more.Delete prospects before creating more
429rate_limitedToo many requests. Please try again in a moment.Retry after Retry-After (or a few seconds)
429test_quota_exceededSandbox quota reached (1,000 calls per day with an fw_test_ key). Try again tomorrow.Retry after Retry-After (or a few seconds)
500internal_errorAn unexpected error occurred. Please try again.Retry with a growing delay and the same Idempotency-Key
500database_errorThe data could not be read or saved. Please try again.Retry with a growing delay and the same Idempotency-Key
502geocode_unavailableGeocoding is temporarily unavailable.Retry with a growing delay and the same Idempotency-Key
502route_unavailableRoute calculation is temporarily unavailable.Retry with a growing delay and the same Idempotency-Key
502upstream_errorA partner service is not responding. Please try again in a moment.Retry with a growing delay and the same Idempotency-Key
503unavailableThis service is temporarily unavailable. Please try again in a moment.Retry after Retry-After (or a few seconds)

New codes may appear for new cases: handle an unknown code according to its HTTP status.

What the details carry

  • insufficient_scope: details.required (the scope needed) and details.granted (the key's scopes) — see scopes.
  • plan_required: details.module and details.tier (the minimum plan) — see plans and AI.
  • rate_limited and test_quota_exceeded: details.retryAfter, in seconds, like the Retry-After header.

Retrying safely

  • 4xx: do not retry unchanged, fix the request first — except 429 (wait for Retry-After) and 409 idempotency_in_progress (retry in a second).
  • 500, 502, 503, timeout or dropped connection: retry with a growing delay (1 s, 5 s, 30 s…), with the same Idempotency-Key. You do not know whether the first request went through; the key ensures it runs only once (idempotency).
  • Quote the response's X-Request-Id header if you write to us: it finds your request in our logs.