Errors, status codes and retries

Errors come back as JSON with a statusCode and a message:

error-bodyjson

{ "statusCode": 404, "message": "Payee not found" }

What the codes mean

Code	Meaning	Retry?
400	The request body or a parameter failed validation. The message says which field.	No. Fix the request.
401	Missing or expired token, or the account does not belong to the caller.	Refresh the token once, retry once.
403	The token is valid but lacks the scope for this endpoint.	No. Ask for the scope.
404	The account, payee, transaction or approval does not exist or is not yours.	No.
429	On payee endpoints this means the account is not active. Elsewhere, too many requests.	Payee: no. Rate limit: yes, after backing off.
500	Something failed on the Xace side.	Yes, with backoff, for reads. See below for writes.

Retrying reads

GET requests are safe to retry. Use exponential backoff with jitter: wait one second, then two, then four, up to a small cap, and give up after five attempts. Log the request and the final failure.

Retrying writes

Creating a payee or a payment is where a naive retry hurts. A request that timed out may have succeeded on the server.

Payments: every POST /payments requires an x-idempotent-key header. Retry with the same key and the same body and the API will not create a second payment. See Idempotency and safe retries.
Payees: prefer the upsert endpoint POST /account/{xaid}/payee. On retry, look the payee up first (by your own reference or by name) and pass xpid if it already exists.

Never retry a payment with a new idempotency key

A new key is a new payment. If you are not sure whether the first request landed, query approvals or transactions before sending again.

Validation failures on batches

POST /payments accepts an array. The response separates submitted from rejected, with an error string per rejected item. A 202 does not mean every payment was accepted; check rejectedCount and handle the rejected list rather than resubmitting the whole batch.

What to log

The request ID from payment responses.
xtid, xpid or ref for anything you created or fetched.
Status code and message on every failure.

Never log tokens, secrets or full account numbers.