Required headers

Every request needs a minimum set of headers before it does anything useful — some are enforced right at the edge, before your request ever reaches the API. This page lists all of them in one place; authentication and request signing cover the two most involved ones in depth.

The full list

Header	Required on	Value
User-Agent	Every request	Non-empty, identifying your system — e.g. acme-payments/2.3
Accept	Every request	application/json
Authorization	Every request	Basic on /oauth2/token, Bearer <token> everywhere else
Content-Type	Requests with a body	application/json
signature + nonce	Signed endpoints	RSA-SHA256 signature and epoch-ms nonce
X-Idempotency-Key	POST /orders only	A unique string you choose — see idempotency

User-Agent and Accept

These two are checked at the gateway edge, before your request reaches the API. Miss either one and you get a generic gateway rejection instead of the JSON error envelope described in errors — there is no code, no category, nothing to branch on.

• User-Agent must be non-empty and should identify your system, not just fall back to a library default — acme-payments/2.3 rather than nothing at all.
• Accept should be application/json.

curl and most HTTP libraries send both by default (Accept: */* and a library User-Agent), which is why this rarely bites anyone testing with curl. It shows up with clients that don't fill these in: Java's java.net.http.HttpClient sends no Accept header at all, and some minimal HTTP libraries or serverless runtimes send a blank User-Agent. Both get blocked.

curl "https://api.gateway.sandbox.retorna.app/me/routes?sourceCurrency=USDR" \
  -H "User-Agent: acme-payments/2.3" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "signature: $SIGNATURE" -H "nonce: $NONCE"

If you use one of the SDKs

The TypeScript, Java and Python SDKs send User-Agent, X-Retorna-Client and Accept: application/json on every request automatically. If you integrate through one of them, there is nothing to add.