Error Handling

All errors follow a consistent envelope format with a machine-readable tag and actionable guidance.

Error response format

{
  "_tag": "ParseError",
  "type": "ParseError",
  "message": "Failed to parse QR code: invalid checksum",
  "docs_url": "https://docs.borderli.dev/errors/ParseError",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Field	Description
`_tag`	Machine-readable error type (use this for programmatic handling)
`message`	Human-readable description
`docs_url`	Link to detailed error documentation
`request_id`	Unique request ID for support correlation

Error types

Error	Status	Retry?	Description
`ParseError`	400	No	QR code could not be parsed
`IdempotencyConflict`	400	No	Key reused with different body
`IdempotencyInProgress`	409	Yes	Same key still being processed
`AuthError`	401	No	Missing or invalid API key
`ValidationError`	422	No	Request validation failed
`UnsupportedScheme`	422	No	QR scheme not supported
`AmountRequired`	422	Add amount	Open-amount QR needs an explicit amount
`InstructionExpired`	422	Re-resolve	Payment instruction expired
`FxQuoteExpired`	422	Re-resolve	FX quote expired
`RateLimitError`	429	Yes	Rate limit exceeded
`RoutingError`	502	Yes	No provider available
`FxError`	502	Yes	FX quote failed
`ExecutionError`	502	Yes	Payment rail rejected transaction
`ServiceUnavailable`	503	Yes	Downstream dependency unavailable

Retry guidance

4xx errors (except 409 and 429): Do not retry. Fix the request.
409 IdempotencyInProgress: The original request is still processing. Retry the same request (same key) after a short delay.
429 RateLimitError: Wait for retryAfter seconds, then retry.
5xx errors: Retry with exponential backoff. Use the same idempotency key.
InstructionExpired / FxQuoteExpired: Re-resolve the QR code to get a fresh instruction.
AmountRequired: The QR is open-amount. Retry with an amount (minor units).