Errors

Every error returns the same JSON body. Branch on code when you recognize it, fall back to type when you don't, and handle the cases in Handle common errors.

The error body

An error body

{
  "type": "failed_precondition",
  "code": "quote_stale",
  "message": "quote expired before it landed; request a new quote",
  "request_id": "7b1f0c2e-5a9d-4e36-8f10-2d4c6b8a9e31"
}

Field	Meaning
type	The category of error. There is a fixed set of types, and each one maps to one HTTP status.
code	The specific condition, such as quote_stale. We add codes over time, so handle the ones you know and fall back to type for the rest. Omitted when no specific condition applies.
message	A description for people. Don't branch on it, because the wording can change.
request_id	Our id for the request. Include it when you write to support. Send your own X-Request-Id header and we use that instead.
field_violations	On invalid_argument, the fields that failed validation and why.
metadata	Extra string values for the code. Which keys appear depends on the code.

Status for each type

type	Status
invalid_argument	400
unauthenticated	401
permission_denied	403
not_found	404
method_not_allowed	405
conflict	409
failed_precondition	422
resource_exhausted	429
internal	500
unavailable	503

Handle common errors

You see	Do this
401	Check the token and, for a Gateway call, the TM-On-Behalf-Of header. Mint or refresh the token once; retrying without a change fails the same way.
422 with quote_stale	The quote expired. Place the order again and execute right away.
201 with an empty order_id	No order was created, and quote.issues says why. Usually the wallet can't fund the buy: fund it and place the order again.
422 with insufficient_balance	The wallet can't fund a sell or perpetual order. Fund it, then place the order again.
409 with already_submitted on execute	The transaction already landed. Don't resubmit; read the order.
429	You sent too many requests. Back off, then retry. Your token is still valid.
503 when you create a user	Repeat the same request. It finishes creating the wallets.
500 or 503 on other calls	Retry with backoff. If it keeps failing, send us the request_id.

Next: the API reference has the responses for each endpoint.