Errors & Rate Limits

The /v1/invoices API returns errors as:

{
  "error": {
    "code": "INVALID_AMOUNT",
    "message": "Human-readable diagnostic"
  }
}

HTTP	Code	Meaning / action
`400`	`INVALID_REQUEST`	Fix unknown or invalid fields
`400`	`INVALID_AMOUNT`	Send a valid positive decimal string
`400`	`UNSUPPORTED_ASSET`	Use an enabled asset
`400`	`UNSUPPORTED_NETWORK`	Use an enabled network
`400`	`WALLET_NOT_CONFIGURED`	Add a compatible active wallet
`401`	`INVALID_API_KEY`	Check or rotate the secret key
`404`	`INVOICE_NOT_FOUND`	Check the ID and project key
`409`	`IDEMPOTENCY_CONFLICT`	Do not change input under the same key
`409`	`PROJECT_NOT_READY`	Complete project readiness or fund the service balance
`429`	`RATE_LIMITED`	Back off with jitter, then retry safely
`500`	`TEMPORARILY_UNAVAILABLE`	Retry with the same idempotency key

BramaPay applies Redis-backed throttling, but its exact global thresholds are environment configuration rather than a stable public quota. Treat 429 as authoritative, use exponential backoff with jitter, and never create a new idempotency key merely because a request timed out. The public checkout invoice lookup is currently limited to 60 requests per minute; normal checkout already polls at a safe interval.