Errors

Failed requests return JSON (not an empty body). The usual shape is:

{
  "error": "invalid_credentials",
  "message": "Invalid email or password"
}

Validation failures may also include a details array from Zod. Treat error as a stable machine code and message as human-readable (some customer-facing messages are in Croatian).

HTTP status

Status Meaning
400 Validation or bad input
401 Missing/invalid token or failed login
403 Authenticated but not allowed (role, tier, suspended)
404 Resource not found or not owned by the caller
409 Conflict (duplicate e-mail, GTIN, folder name, sender address)
429 Rate limited
500 / 502 / 503 Upstream or configuration failure (e-mail, OCR, mint, storage)

Common error codes

error Typical HTTP Notes
unauthorized 401 Missing, malformed, or unverifiable JWT
forbidden 403 Role or subscription tier does not allow the action
invalid_credentials 401 Login failed
account_suspended 403 User is suspended
merchant_suspended 403 Merchant organisation is not ACTIVE
validation_error 400 Body/query failed schema checks
not_found 404 Warranty, receipt, folder, merchant, product, or sender address
invalid_token / expired_token / token_used 401 Magic-link lifecycle
expired / invalid_link 401 Claim-link lifecycle
too_many_requests 429 Claim-link resend
email_taken 409 Admin creating a merchant user
duplicate_gtin 409 Global product GTIN already exists
product_in_use 409 Cannot delete a global product that is referenced
already_registered 409 Merchant sender address
already_verified 409 Resend verification for a verified sender
email_failed 502 Outbound mail could not be sent
ocr_failed 500 Receipt OCR unavailable
warranty_issue_failed / retry_mint_failed 500 Mint / issue pipeline
unavailable 503 Receipt storage/sharing not configured

Merchant-only examples: missing_merchant_id, missing_product_reference, missing_customer_identifier, product_not_found, warranty_not_found.

Interactive reference

Request/response schemas for documented routes live in the API Reference and OpenAPI spec. Some newer customer and merchant routes (receipts, inbox, sender addresses) are described in these guides even when the spec is still catching up — prefer the running API and these pages if the two disagree.