Limits, rate limits and error responses
socket.help plan allowances, rate limits, request sizes and retention, plus the JSON error format, status codes and how to handle Retry-After on 429 and 503.
Updated 27 October 2026How limits work
Every hosted request counts against the caller’s plan: anonymous, Free, Pro or Team. Account limits are shared by all API keys and members of a workspace. Anonymous limits are keyed to a hashed IP address. Browser-local tools on the website run on your device and use no hosted allowance.
Call GET /api/plans for all plan allowances and GET /api/usage for your current plan, its limits and today’s hosted runs. Daily run counters reset at 00:00 UTC.
| Allowance | Without an account | Free | Pro | Team |
|---|---|---|---|---|
| Active resources | 5 | 20 | 100 | 500 |
| Total storage | 32 MiB | 64 MiB | 512 MiB | 2 GiB |
| Maximum retention | 1 hour | 1 day | 7 days | 30 days |
| Hosted utility runs per day | 100 | 1,000 | 20,000 | 100,000 |
| Utility input per request | 64 KiB | 256 KiB | 1024 KiB | 1024 KiB |
| API requests per minute | 120 | 240 | 1,200 | 3,000 |
| Resource creations per minute | 10 | 20 | 60 | 120 |
| File size per upload | 10 MiB | 10 MiB | 10 MiB | 10 MiB |
| Persistent leases | No | No | Yes | Yes |
Request and resource limits
These limits apply regardless of plan unless the table says otherwise. The installation can also reach total capacity, in which case creation returns 503.
| Limit | Value |
|---|---|
| JSON request body for most /api/ endpoints | 100 KiB |
| Utility run request body | 16 MiB, with files up to 10 MiB combined |
| Webhook request body | 100 KiB |
| Webhook inbox history | 100 requests or 1 MiB anonymously; 1,000 requests or 10 MiB with an account |
| File upload | 10 MiB, nonempty |
| Downloads per file | Up to 100 anonymously, up to 1,000 with an account |
| Mock API configuration | 1 to 20 routes, 80 KiB total |
| Mock MCP server configuration | 1 to 10 tools, 80 KiB total |
| Platform MCP request body | 16 MiB; four concurrent requests |
| Public endpoint rate (each webhook inbox, mock API and mock MCP server) | 120 requests per minute |
| Sign-in and registration attempts | 10 per 15 minutes per IP address |
Error format
Errors are JSON objects with an error message. Most API errors also include requestId. Every response carries an X-Request-Id header, so keep that value when you report a failed call. The platform MCP endpoint returns JSON-RPC errors instead.
HTTP/1.1 429 Too Many Requests
Retry-After: 37
X-Request-Id: 1e3e28f5-fb64-474f-845f-b06c17f52eef
{"error":"Request rate limit exceeded.","requestId":"1e3e28f5-fb64-474f-845f-b06c17f52eef"}Status codes
Read each endpoint’s schema in /docs/reference/ for its exact responses. These are the codes you will meet most often.
| Status | Meaning | What to do |
|---|---|---|
| 200, 201, 204 | Success, created, or done with no body | Continue. |
| 304 | Inbox history unchanged since your ETag | Keep the cached history. |
| 400 | Invalid body, option, visibility, ttlSeconds or maxDownloads | Fix the request using the error message. |
| 401 | Missing, invalid, expired or revoked credential | Check the API key or sign in. |
| 403 | Scope, role or Origin not allowed, or persistent requested without a paid plan | Use a key with the right scope; call from a server, not a third-party page. |
| 404 | Unknown, expired or inaccessible resource, or a missing access token | Check the ID, the token and whether the resource expired. |
| 408 | A utility run timed out | Reduce the input or try again later. |
| 409 | Renewal past the maximum lifetime, key or invitation limit reached | Create a new resource, or revoke unused keys. |
| 413 | Body or input exceeds the allowance | Send less data. |
| 429 | Rate limit, daily run allowance, resource quota or full inbox | Wait for Retry-After when present; otherwise free capacity first. |
| 503 | Processors, file transfers or capacity busy | Retry after the Retry-After seconds. |
Handling 429 and 503
Rate limits use one-minute windows. A 429 from a rate limit includes Retry-After in seconds until the window resets. The daily run limit returns 429 with Retry-After set to the seconds until 00:00 UTC.
Some 429 responses have no Retry-After because waiting will not help: a full webhook inbox, the active resource limit or the storage allowance. Delete resources or create a new inbox instead.
When hosted tool processors are busy the API returns 503 with Retry-After: 2. When file transfers are busy it returns 503 with Retry-After: 5.
- Retry GET requests and utility runs after Retry-After.
- Do not blindly retry creation requests; check whether the first one succeeded.
- The SDK exposes retryAfter on SocketError. The SDK and CLI never retry mutations themselves.
Retention and cleanup
Resources expire one hour after creation unless you set ttlSeconds or renew them within your plan’s maximum retention. Expired resources stop working immediately, and cleanup removes their data and releases quota at least once per minute. Expired data cannot be restored.
Utility runs keep no execution history: inputs and results are not stored.
Frequently asked questions
When do hosted run counters reset?
Daily hosted run counters reset at 00:00 UTC. The usage object returned by each run includes resetsAt.
Do failed utility runs count against my daily allowance?
Requests rejected during validation, for example an unknown option or oversized input, are rejected before a run is counted. A run that fails during processing is released from the count.
Are limits per API key or per workspace?
Per workspace. All keys and members of a workspace share its allowances. Anonymous callers are grouped by a hashed IP address.
Why do I get 429 when my inbox is not receiving much traffic?
An inbox stops capturing when its history is full: 100 requests or 1 MiB anonymously, 1,000 requests or 10 MiB with an account. Existing history stays readable. Create another inbox or delete this one.