API reference
Errors
Every error the API returns, what causes it and what to do.
Errors are returned as a non-2xx status with a JSON body:
{ "error": "Expected nonce 1" }Submitting transfers
| Status | Error | Cause and fix |
|---|---|---|
| 400 | Addresses must be 0x… EVM addresses | Check from and to |
| 400 | Sender and recipient are the same | Send to a different address |
| 400 | Amount must be a positive USDT amount with up to 6 decimals | Use a decimal string such as "12.5" |
| 400 | Fee must be 0.01 USDT | Send "fee": "0.01" and sign Fee: 0.01 USDT |
| 400 | Bad nonce | Nonce must be a non-negative integer |
| 400 | Memo is limited to 140 characters | Shorten the memo |
| 400 | Send JSON | The body was not valid JSON |
| 401 | Signature does not match the sender | The message you signed differs from what the network rebuilt. See Signing transfers. |
| 402 | Insufficient USDT for amount and fee | The balance must cover amount plus 0.01 |
| 403 | This address is frozen under the issuer policy | The sender is frozen. See Issuer controls. |
| 403 | The recipient address is frozen | The recipient cannot receive USD₮ |
| 409 | Expected nonce n | Read the nonce again from /address and re-sign |
Faucet
| Status | Error | Cause |
|---|---|---|
| 400 | Use a 0x… address | The address is not valid |
| 403 | This address is frozen | Frozen addresses cannot receive |
| 429 | Test USDT can be requested once every 24 hours per address | Wait, or use another address |
| 429 | Please wait a minute between requests | Rate limit per IP address |
| 429 | Too many requests. Try again in a minute. | A rate limit was hit; wait retry-after seconds |
Reads
| Status | Error | Cause |
|---|---|---|
| 404 | Block not found | The height has not been sealed yet |
| 404 | Transaction not found | Unknown hash, or the transfer was never accepted |
| 404 | Height outside the log | Inclusion proof for a block that does not exist |
| 400 | Bad range | Consistency proof with from of 0 or above to |
| 404 | Unknown endpoint | Check the path |
| 500 | Any | Server error. Retry with backoff. |
Failed at sealing
A transfer can pass submission checks and still fail when it is sealed, if the state changed in between. It is then stored with "status": "failed" and one of these errors, and no fee is charged:
| Error | Meaning |
|---|---|
Frozen address | One side was frozen before sealing |
Nonce n is stale, expected m | Another transfer from the sender was sealed first |
Insufficient balance | Another transfer spent the balance first |