Errors & rate limits
Predictable, typed errors and generous limits so your integration fails loudly and recovers gracefully.
Error shape
Every API and SDK error follows the same structure:
json
{
"error": {
"code": "insufficient_trust",
"message": "Agent score 612 is below the required 820.",
"status": 403
}
}Error codes
| Field | Type | Description |
|---|---|---|
| unauthorized | 401 | Missing or invalid API key. |
| insufficient_trust | 403 | Agent failed the supplied policy. |
| agent_not_found | 404 | No identity exists for the given handle. |
| attestation_unsigned | 409 | Attestation is not yet co-signed. |
| rate_limited | 429 | Too many requests — back off and retry. |
| internal | 500 | Unexpected error. Safe to retry idempotent reads. |
Rate limits
| Field | Type | Description |
|---|---|---|
| Reads (no key) | 60 / min | Per IP. Best-effort, cached. |
| Reads (with key) | 1,000 / min | Per project key. |
| Writes | 120 / min | Attestations and stake operations. |
| Webhooks | — | No limit; deliveries are queued. |
Handling 429s
Responses include Retry-After and X-RateLimit-Remaining headers. The SDK retries 429 and 5xx automatically with jittered backoff.
typescript
const tessera = new Tessera({
cluster: "mainnet-beta",
maxRetries: 4, // default 3
retryBaseMs: 250,
});Need higher limits? They scale with your project tier — reach out and we lift them in minutes.