Errors

Errors are returned as application/problem+json (RFC 9457):

{
  "type": "https://maticna.si/docs/errors/invalid_tax_number",
  "title": "Invalid tax number",
  "status": 422,
  "detail": "12345679 fails the mod-11 check.",
  "instance": "/v1/entities/12345679",
  "code": "invalid_tax_number",
  "request_id": "req_01JB2Q8X6S7T",
  "errors": [{ "field": "tax_number", "code": "checksum" }]
}

• Branch on code, not on title or detail (those are translated and may change).
• type is the URL of the page explaining the code.
• request_id equals the X-Request-Id header. Include it when you contact us.
• title and detail follow Accept-Language: sl|en; English is the default.
• New codes can appear at any time; handle an unknown code by its HTTP status.
• 4xx and 5xx errors are not billed, except a 404 on a well-formed identifier (Billable units).

All codes

Status	Code	Meaning
400	bad_request	Bad request
400	key_in_query_forbidden	API key in query string is forbidden
401	missing_api_key	Missing API key
401	invalid_api_key	Invalid API key
401	key_revoked	API key revoked
401	key_expired	API key expired
401	test_keys_removed	Test keys were discontinued
402	payment_required	Payment required
403	insufficient_scope	Insufficient scope
403	plan_upgrade_required	Plan upgrade required
403	origin_not_allowed	Origin not allowed
403	monitor_limit_reached	Monitor limit reached
403	webhook_endpoint_limit_reached	Webhook endpoint limit reached
403	ip_not_allowed	IP address not allowed
404	not_found	Not found
404	not_vat_registered	Not VAT registered
409	cursor_expired	Cursor expired
409	idempotency_conflict	Idempotency key reused with a different request
422	invalid_tax_number	Invalid tax number
422	invalid_vat_id	Invalid VAT ID
422	invalid_registration_number	Invalid registration number
422	query_too_short	Query too short
422	invalid_webhook_url	Invalid webhook URL
429	rate_limited	Rate limited
429	quota_exceeded	Quota exceeded
429	natural_person_cap_exceeded	Daily natural-person lookup cap exceeded
500	internal_error	Internal error
503	upstream_stale	Data temporarily stale
503	search_timeout	Search timed out