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.
| Code | HTTP | Meaning | Next step | Units |
|---|---|---|---|---|
invalid_request | 400 (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_identifier | 400 | The 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_identifier | 400 | The 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_supported | 400 | The 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_supported | 404 | Fuentio doesn't know this country. | Use a covered country code: GET /v1/countries lists them. | 0 |
coverage_unavailable | 404 | The 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_found | 404 | A 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 |
unauthorized | 401 | The 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_limited | 429 | Too 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_large | 413 | The 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_exceeded | 402 | Units 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_exists | 409 | One 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_unavailable | 503 (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_error | 500 | Our 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.