Errors

Every error is an RFC 9457 problem, with Content-Type: application/problem+json:

{
  "type": "https://docs.txgold.money/errors/insufficient_balance",
  "title": "Insufficient balance",
  "status": 422,
  "code": "insufficient_balance",
  "detail": "Insufficient Balance to process transaction",
  "requestId": "7219af94e39d"
}

• code is what your code branches on. It never changes once published; the title and detail text may. New codes can be added at any time, so handle unknown ones by their status.
• requestId is also in the X-Request-Id header of every response. Quote it to TxGold support.
• errors appears on invalid_request: each bad field with its problems.
• The SDKs raise one exception type with these fields: TxGoldApiError (JavaScript, Python) and TxGoldApiException (C#).

What the statuses mean:

Status	Meaning	Retry?
400	The request is wrong	No: fix it first
401	Who's calling can't be established	No: fix the key, clock or signature
403	The key may not do this	No
404	Not found, or not yours	No
409	Conflicts with the current state	No
413	Body over 64 KB	No
422	Well-formed, but a business rule refuses it	Not without changing something
500, 503	TxGold's side	Yes, with the same timestamp (how)

All codes

Code	Status	Title
invalid_request	400	Invalid request
invalid_signature	401	Invalid signature
timestamp_out_of_range	401	Timestamp out of range
key_not_found	401	Key not found
key_expired	401	Key expired
forbidden	403	Forbidden
not_found	404	Not found
duplicate_request	409	Duplicate request
already_refunded	409	Already refunded
request_not_pending	409	Payment request is not pending
payload_too_large	413	Payload too large
insufficient_balance	422	Insufficient balance
same_account	422	Source and destination are the same account
amount_below_minimum	422	Amount below minimum
source_account_inactive	422	Source account inactive
identity_check_required	422	Identity check required
destination_account_invalid	422	Destination account invalid
daily_send_limit_exceeded	422	Daily send limit exceeded
recipient_balance_limit_exceeded	422	Recipient balance limit exceeded
refund_exceeds_original	422	Refund exceeds original payment
amount_must_match_request	422	Amount must match the payment request
payment_request_not_payable	422	Payment request cancelled or expired
payer_account_invalid	422	Payer account invalid
payer_not_demo_customer	422	Payer is not a sandbox demo customer
business_rule_violation	422	Business rule violation
internal_error	500	Internal error
rate_unavailable	503	Rate unavailable
sandbox_unavailable	503	Sandbox unavailable

Business portal codes

These go to the business portal and the TxGold app. Integrations don't receive them.

Code	Status	Title
session_not_found	401	Portal session not found
session_expired	401	Portal session expired
sign_in_pending	401	Sign-in not yet approved
not_pending	409	Not pending
key_already_registered	409	Key already registered
approval_required	422	Approval required