Errors

Errors come back as JSON with an HTTP status and a message. Quote and transaction errors also carry title, detail and extra with the specifics. Successful POST calls return 201, not 200: treat any 2xx as success. Retryable means you can send the same request again, after a backoff, and expect it to succeed. No means the same request will fail again: change what the “What to do” column says first.

Swap endpoints

/quote, /quote/build, /swap and /send.

Status	Message	When	Retryable	What to do
400	`No path found`	No route exists between the two assets for that amount, with the venues in `protocols`	No	Add venues to `protocols`, try a smaller amount, or check that both assets have liquidity
400	`Invalid Stellar address`	`assetIn` or `assetOut` is not a contract address, for example `CODE:ISSUER`	No	Send contract addresses (`C...`); see Stellar gotchas
400	`amount must be a positive integer number of stroops`	`amount` is zero or negative	No	Send the amount in the asset’s smallest unit, as a positive integer string
400	`Amount too small: the fee leaves nothing to swap`	The fee takes the whole `EXACT_IN` amount	No	Send a larger amount
400	`Each value in protocols must be a supported protocol`	`protocols` is missing or has an unknown value	No	Send values from `GET /protocols?network=...`
400	`Unsupported network: ...`	`?network=` is not `mainnet` or `testnet`	No	Send `?network=mainnet` or `?network=testnet`
400	`Slippage tolerance must be between 0 and 10000 bps`	`slippageBps` out of range or not a whole number	No	Send a whole number of basis points: `50` is 0.5%
400	`sdex is not available for contract (C) addresses; include at least one Soroban protocol`	`from` or `to` is a contract and `sdex` was the only venue	No	Add a Soroban venue to `protocols`; see Routing through SDEX
400	`Soroban routes deliver to the signing account only: to must equal from (or be omitted)`	`/quote/build` on a Soroban route with a different `to`	No	Leave `to` out, or send the output to the other account in a separate payment
400	`invalid version byte. expected 48, got 16`	`from` on `/quote/build` is a contract (`C...`)	No	Smart wallets execute from the contract path; see Stellar gotchas
400	`Gasless trustline is only supported with SDEX`	`gaslessTrustline` without `sdex` in `protocols`	No	Add `sdex`, or drop `gaslessTrustline`; see Gasless Trustline
400	`sponsor is required when gaslessTrustline is ...`	A gasless trustline build or swap without `sponsor`	No	Send the sponsor’s `G...` address
400	`Simulation Failed`	The transaction fails when simulated. `errorCode` is the contract error, for example `10` (`TokenError.InsufficientBalance`)	No	Read `errorCode` and `extra`, fix the account state (balance, reserve) and build again
400	`Invalid contract address, not a soroswap contract`	`/send` got a Soroban transaction that does not call a venue the API routes through	No	Submit it through your own Soroban RPC, or send only XDRs built by the API
400	`Transaction Failed`	`/send` submitted the transaction and the network rejected it, for example `tx_too_late`	No	Read `detail` and `extra`; quote and build again before you resubmit. Never resend the same XDR
409	`Quote stale`	Your partner fee changed between `/quote` and `/quote/build`, so the quote’s fee no longer matches	No	Quote again and build from the new quote
428	`CREATE_TRUSTLINE`	The receiving account has no trustline for an asset of the route	After the prerequisite	Sign and submit `actionData.xdr`, then build again, or use Gasless Trustline
429	`Rate limit exceeded`	You are over your plan’s request rate	Yes	Wait `Retry-After` seconds (also `retryAfter` in the body); see Plans and rate limits
500	`Internal server error`	Seen when `amount` has a decimal point, for example `"10.5"`	No	Send an integer string. If your input was valid, report it with the request body
503	`Routing unavailable`	The routing service could not answer. Also returned when `assetIn` or `assetOut` is a `G...` address	Yes, if your addresses are `C...`	Retry with backoff. If it persists for one pair only, check the asset addresses

POST /swap behaves differently from /quote/build on a missing trustline: it returns 200 with an action field (CREATE_TRUSTLINE, RESTORE_BALANCE, RESTORE_CONTRACT) instead of an error, so a single call can carry the prerequisite. Sign and submit the xdr of that action, then call /swap again.

Authentication

Any route that needs a credential.

Status	Message	When	Retryable	What to do
401	`Missing credential. Get an API key at ...`	`code` is `MISSING_CREDENTIAL`. No `Authorization` header, or `Bearer` with no token	No	Get a key at `registerUrl` and send `Authorization: Bearer sk_...`
401	`Invalid API key. Get a new one at ...`	`code` is `INVALID_API_KEY`. The `sk_...` key does not exist or was revoked	No	Send an active key, or generate a new one at `registerUrl`
403	`Forbidden resource`	An expired or invalid JWT, an `Authorization` scheme other than `Bearer`, or a valid credential without the role the route needs	No	Log in or refresh for a new JWT, or use an account with the required role

Both 401 answers carry code, registerUrl and a WWW-Authenticate header:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "code": "MISSING_CREDENTIAL",
  "message": "Missing credential. Get an API key at https://console.soroswap.finance/register and send it as \"Authorization: Bearer sk_...\"",
  "registerUrl": "https://console.soroswap.finance/register"
}

POST /send is the exception. It answers 403 Forbidden resource for all of the cases above, with no code, registerUrl or WWW-Authenticate. Handle both statuses if you call it. A key that normally works can also get a 403 when the API could not check it at that moment. Retry with backoff before you replace the key.

Account endpoints

/register, /login, /refresh, /logout, /api-keys, /auth/email/*, /auth/password/* and /users/me/password. A body that fails validation answers 400 with message as an array of strings.

Status	Message	When	Retryable	What to do
400	`password must be at least 15 characters`	`POST /register` with a shorter password. Older accounts keep logging in with the password they have	No	Choose a longer password
400	`newPassword must be at least 15 characters`	`POST /auth/password/reset` or `POST /users/me/password` with a shorter password	No	Choose a longer password
400	`newPassword must differ from the current password`	`POST /users/me/password` with the password in use	No	Choose a different password
400	`Current password is incorrect`	`POST /users/me/password` or `PUT /partner/payout-address` with a wrong current password. Repeated failures lead to the 429 below	No	Check the password, or reset it with `POST /auth/password/forgot`
400	`Disposable email addresses are not allowed`	`POST /register` with a disposable email domain	No	Use a permanent address
400	`The security check failed. Please try it again.`	`POST /register` without a valid security token, which is what a scripted sign-up gets	No	Sign up in the console
400	`Invalid or expired PIN`	`POST /auth/email/verify` or `POST /auth/password/reset` with a PIN that is wrong, expired or already used	No	Request a new PIN with `POST /auth/email/resend` or `POST /auth/password/forgot`
401	`Invalid email or password`	`POST /login` with a wrong password or an unknown email	No	Check the credentials. Repeated failures lead to the 429 below
401	`Account disabled`	`POST /login` with the right password, or `POST /refresh` or any call with a session of a disabled account	No	Write to dev@paltalabs.io
401	`Unauthorized`	No `code`. `POST /refresh` with a missing, malformed or expired refresh token, or an API key sent to `/api-keys` or `/logout`, which take a console session	No	Log in, and send the JWT or refresh token the route asks for
403	`Access Denied`	`POST /refresh` with a refresh token that is invalid or was already used, or after a logout	No	Log in again for a new refresh token
403	`Verify your email first`	`POST /api-keys/generate` or `PUT /partner/payout-address` before the account verified its address. Keys it already has keep working	No	Verify with the emailed PIN through `POST /auth/email/verify`
403	`This route takes a console session, not an API key`	`POST /users/me/password` with an API key	No	Send the JWT from `POST /login` or `POST /refresh`
403	`This account has no password to change. Set one with Forgot password on the sign-in page`	`POST /users/me/password` on an account with no usable password	No	Set one with `POST /auth/password/forgot` and `POST /auth/password/reset`
409	`The password changed while this request ran. Sign in again`	`POST /users/me/password` raced another password change. Nothing was written	No	Log in again with the current password
409	`User already exists`	`POST /register` with an email that has an account	No	Sign in instead
429	`Too many attempts. Try again in N minutes.`	Too many failed passwords on `POST /login`, `POST /users/me/password` or `PUT /partner/payout-address`, or too many sign-ups on `POST /register`. While locked, the right password is refused too	After the wait	Wait `Retry-After` seconds (also `retryAfter` in the body), then try once
429	`Too many attempts, try again later`	Too many requests or guesses on `/auth/email/` or `/auth/password/`	After the wait	Wait `Retry-After` seconds (also `retryAfter` in the body)
503	`Could not run the security check right now. Try again in a minute.`	`POST /register` while the security check is unavailable	Yes	Try again in a minute

Retry policy in one line

Retry 429 after Retry-After and 503 with exponential backoff. Resolve 428 and build again. Quote again on 409 and on any build older than its time bound. Never retry a 400, 401, 403 or 500 unchanged.

Get started

Guides

Execute from your own contract

Monetize

Production

Swap endpoints

Authentication

Account endpoints

Retry policy in one line

​Swap endpoints

​Authentication

​Account endpoints

​Retry policy in one line

Swap endpoints

Authentication

Account endpoints

Retry policy in one line