Error Handling

The Revolutio API uses standard HTTP status codes and returns errors as JSON objects.

Error response format

{
  "error": "Human-readable error message"
}

Some errors include additional context fields:

{
  "error": "Insufficient subscription: you are not subscribed to search in this jurisdiction",
  "jurisdiction": "DE",
  "hint": "Check your subscription coverage or contact support"
}

{
  "error": "Insufficient credits. This search requires 5 credit(s).",
  "volume_remaining": 0,
  "cost": 5
}

HTTP status codes

Code	Meaning	Common causes
200	Success	Request completed (check status on async searches). Document downloads return the PDF body.
400	Bad Request	Missing required fields, invalid jurisdiction, malformed IDs
401	Unauthorized	Missing/invalid credentials, expired ID token, revoked API key
402	Payment Required	Insufficient volume_remaining
403	Forbidden	Jurisdiction not subscribed; account locked; not case owner
404	Not Found	Search, case, document, or user profile missing
405	Method Not Allowed	Wrong HTTP method
409	Conflict	Expand already done or already PENDING for that entity
429	Too Many Requests	Search rate limit or auth lockout
500	Internal Server Error	Server-side failure (search/IDFinder credits refunded when applicable)
502	Bad Gateway	Upstream auth or registry failure

Common scenarios

Authentication

{ "error": "Email and password must be provided" }
{ "error": "INVALID_PASSWORD" }
{ "error": "Too many attempts. Try again later." }
{ "error": "Missing Authorization or X-API-Key header" }
{ "error": "Invalid or expired token" }
{ "error": "Your account access has been suspended. Please contact support." }

Search / expand

{ "error": "Missing identifier and/or jurisdiction input" }
{ "error": "Missing legal_name and/or jurisdiction input" }
{ "error": "Unsupported jurisdiction: XX" }
{
  "error": "Insufficient subscription: you are not subscribed to search in this jurisdiction",
  "jurisdiction": "DE",
  "hint": "Check your subscription coverage or contact support"
}
{
  "error": "Insufficient credits. This search requires 5 credit(s).",
  "volume_remaining": 0,
  "cost": 5
}
{ "error": "Rate limit exceeded" }
{
  "error": "No registration number for this company. Resolve it first via /idfinder.",
  "legalName": "Example GmbH",
  "jurisdiction": "DE"
}

IDFinder

{ "error": "Missing legalName and/or jurisdiction" }
{
  "error": "Insufficient credits. IDFinder requires 1 credit(s).",
  "cost": 1
}

Empty successful lookup (not an error):

[]

Case / document

{ "error": "Missing caseId" }
{ "error": "Case not found" }
{ "error": "Document not found" }
{ "error": "File not found" }

Automatic credit refunds

Operation	Charged when	Refunded when
Search / expand (base)	Request accepted	Search ends FAILED / processing error
Financials include	Successful numeric financials	Not charged if no financials returned
IDFinder	Request accepted	Empty result or server failure
LEI	Before GLEIF calls	No match or failure

Client errors (4xx other than some mid-flight cases) generally do not consume credits when rejected before processing.