Errors

Envelope

All error responses share the same JSON shape:

{ "error": "<code>" }

The HTTP status carries the kind of failure; the error field carries the specific code. There is no message field — codes are stable machine identifiers, not human strings.

Codes

Code	Status	Meaning
INVALID_KEY	401	The bearer token is missing, malformed, or unknown.
RATE_LIMITED	429	You’re over the per-minute request limit for your plan. The response also includes Retry-After in seconds.
QUOTA_EXCEEDED	429	You’ve used your monthly request allowance. Retry-After carries the seconds until the next CET month (00:00 on the 1st in Europe/Warsaw, DST-aware); X-Quota-Limit and X-Quota-Remaining are also set.
INVALID_INPUT	422	A path or query parameter failed validation (e.g. malformed country code on /vies/).
MS_UNAVAILABLE	503	The upstream Member State VIES service is down. Retry after a short delay.
SERVICE_UNAVAILABLE	503	The upstream VIES root service is degraded.
TIMEOUT	503	The upstream call took longer than our hard timeout.
no data yet	404	/rates or /fx was queried before the first cron tick on a fresh deploy. Should only ever be visible during initial setup.
snapshot not found	404	Returned for a historical /rates/YYYY-MM-DD or /fx/YYYY-MM-DD where no snapshot exists.

Two distinct 429s

Both RATE_LIMITED and QUOTA_EXCEEDED are 429s. They cover different failure modes:

• RATE_LIMITED — too many requests in the current minute. Wait Retry-After seconds and retry.
• QUOTA_EXCEEDED — your monthly allowance is exhausted. Retry-After could be days. Upgrade your plan or wait for the next CET month.

Check the error field, not just the status, to tell them apart.

Upstream failures

VIES is the only Stawka endpoint that fans out to a live upstream on every request. When VIES is degraded, the failure mode you see depends on what we observed:

• INVALID_INPUT — the country or VAT number you passed failed VIES’s own validation. Fix the input.
• MS_UNAVAILABLE — the specific Member State’s tax registry is down. Try again later, or expect intermittent failures while that registry recovers.
• SERVICE_UNAVAILABLE / TIMEOUT — VIES itself is degraded. Same retry guidance.

Everything else surfaces as a 502 with a generic error code; these are bugs on our side or unexpected upstream shapes. Please open an issue with the request URL + timestamp.

What is not in the error envelope

• A stack trace.
• An internal request ID. (One is in the response headers as cf-ray; quote that in support tickets.)
• A user-facing string. Map codes to messages on the client side.