Troubleshooting
Resolve TempoKey wallet, RPC, payment, quota and authorization errors without accidentally sending a duplicate payment.
Wallet and network problems
| Symptom | What to check |
|---|---|
| Install MetaMask is shown | Use a browser with an injected compatible wallet, unlock it and reload the page. |
| Wrong network | Switch the owner wallet to Tempo Mainnet for payment keys, or Robinhood testnet for membership. |
| Old agents disappeared | Mainnet uses separate local storage. Create new mainnet authorizations; testnet records were not migrated. |
| Transaction rejected by wallet | No successful authorization is assumed. Review the request and submit again only when ready. |
HTTP errors
| Status / code | Response |
|---|---|
| 400 / KEY_MISMATCH | The supplied P256 key does not derive the claimed access-key address. |
| 401 | Check the Bearer token and registered agent ID; re-registration invalidates the old token. |
| 403 / KEY_NOT_AUTHORIZED, KEY_EXPIRED, KEY_REVOKED | Verify the authorization on the API's configured Tempo network. |
| 403 / SPENDING_LIMIT_EXCEEDED | Read remaining allowance and reset time; do not bypass the owner's budget. |
| 403 / RECIPIENT_NOT_ALLOWED | Use an approved recipient or have the owner deliberately update permissions. |
| 409 / IDEMPOTENCY_CONFLICT | The same idempotency key was used for a different request. |
| 409 / REQUEST_IN_PROGRESS | Reconcile the original attempt. Do not create a new key to blindly resend it. |
| 429 / OWNER_QUOTA_EXCEEDED | Wait for the indicated quota window using Retry-After. |
| 429 without that code | Per-agent, registration or public-position rate limit; respect Retry-After. |
| 503 on membership position | A fresh confirmed position could not be verified. Retry the read later. |
Payment and swap failures
Check the owner's balance on the correct network, token address, remaining budget, expiry and call permissions. A mainnet wallet can have testnet tokens while holding no mainnet funds.
For swaps, inspect liquidity and slippage and confirm that the agent can approve and call the Tempo DEX. Approval and execution are separate transactions. Reconcile balances and receipts instead of treating the returned quote as final settlement.
Budgets are separate for each token. USDC.e payments use the USDC.e allowance; network fees also consume the allowance for the fee token. The agent card lists both token budgets. Discovered payments are also added to Activity without duplicating local entries.
For a timeout or disconnected RPC, first check whether a transaction hash was produced and whether it was included on-chain. Use the same idempotency key and identical request for an eligible hosted API retry. SDK calls have no hosted replay protection.
Collect useful diagnostics
- Network and chain ID.
- Public owner and access-key addresses.
- Transaction hash, timestamp and endpoint.
- HTTP status, error code and relevant Retry-After header.
- SDK version and whether the request used the direct SDK or hosted API.