Fuentio API errors

Every error uses the same envelope, and code is always one of the closed list below. hint is the next step to take; the MCP server returns the same codes as tool errors, its hint holding a corrected call.

{
  "data": null,
  "meta": { "request_id": "req_..." },
  "error": {
    "code": "invalid_identifier",
    "message": "'441639466' has the format of a SIREN but its check digits are wrong.",
    "hint": "Check for a typo.",
    "docs_url": "https://api.fuentio.com/docs/errors#invalid_identifier",
    "details": { "check": "checksum", "scheme": "FR_SIREN" },
    "outcome": null,
    "outcome_url": null
  }
}

5xx responses never contain a stack trace or internal detail; quote the request_id to support.

Billing: errors cost 0 units, except not_found on a well-formed identifier (1 unit).

Outcome: an error about a company also carries outcome and outcome_url (not_found, not_covered, ambiguous or source_unavailable; null for request, key and quota errors), and meta.outcome says the same. A miss in a country Fuentio covers in part, such as Spain, is not_covered, never not_found. source_unavailable always comes with details.retry_after and a Retry-After header. Meanings: https://api.fuentio.com/docs/outcomes.

CodeHTTPMeaningNext stepUnits
invalid_request400 (404/405 for unknown routes)A parameter is missing or out of range, a filter isn't supported for this country, or the route doesn't exist.Fix the parameter named in the message; GET /openapi.json lists every parameter.0
invalid_identifier400The identifier doesn't match any format for the country (details.check = "format"), or matches one but its check digits are wrong ("checksum").Check the number for a typo; GET /v1/countries lists each country's ID formats with examples.0
ambiguous_identifier400The identifier fits several ID types of the country (a number that matches two of its ID formats). When exactly one of them holds a record, Fuentio answers with it and says which type matched (meta.id_scheme_matched); this error comes only when several hold a record, or none does. details.candidates lists each type, with found: true when Fuentio holds a record for exactly that ID.Call again with id_scheme set to one of details.candidates (those with found: true have a record).0
id_scheme_not_supported400The scheme exists for the country but Fuentio can't look it up yet (e.g. a Spanish NIF/CIF), or id_scheme names an unknown scheme.Use another identifier listed in GET /v1/countries, or search by company name.0
country_not_supported404Fuentio doesn't know this country.Use a covered country code: GET /v1/countries lists them.0
coverage_unavailable404The country is known but not enabled yet (planned, or switched off). A malformed identifier is still reported as invalid_identifier.This country isn't enabled yet; GET /v1/countries lists the countries Fuentio covers today.0
not_found404A well-formed identifier with no public record. For France, the company may have opted out of public diffusion; for Spain, it may have no BORME act since the backfill start. This is a real answer: it costs 1 unit.Check the number, or search by company name.1
unauthorized401The API key sent is unknown or revoked. (No key at all = keyless trial, not an error.)Get a free key with POST /v1/keys, or call without a key for the keyless trial (20 units a day).0
rate_limited429Too many requests per second for your plan (keyless 1/s, Free 2/s, …), after a first burst at once (5, or twice the plan's rate if higher).Wait the seconds in the Retry-After header (also details.retry_after), then retry.0
payload_too_large413The request body is over the size limit (64 KB by default; payment webhooks 256 KB). Fuentio requests are small: a name, an identifier, a few options.Send a smaller body: requests carry a company name or an ID, never files (64 KB at most; on /mcp, one JSON-RPC message per request).0
quota_exceeded402Units used up: keyless 20 a day per address; keys per calendar month (Free 100). error.details gives limit, used and resets.Keyless: wait until tomorrow (UTC) or get a free key with POST /v1/keys (100 units a month). Keys: wait for the next period (details.resets) or move to a bigger plan.0
already_exists409One free key per person (Mouad 2026-10-11): POST /v1/keys refuses an email that already has an active free key (case-insensitive) and an address that created a free key in the last 30 days. Paid keys are not affected.Use the free key you already have. Lost it? Write to hello@fuentio.com.0
upstream_unavailable503 (504 when the request ran past the time limit)The official source isn't answering and Fuentio has no earlier copy to serve (when it has one, you get it with meta.stale: true instead). Also sent when a request runs past the time limit (30 s; file exports 120 s): it is stopped.Retry in a minute; the official source didn't answer and no earlier copy is held.0
internal_error500Our fault. No stack trace or internal detail is ever sent.Retry later; quote the request_id if you contact hello@fuentio.com.0

An error about a company also carries outcome and outcome_url: see /docs/outcomes.

Guide for AI agents: /llms.txt. Support: hello@fuentio.com.