Limits and errors
Every limit Porch enforces, what senders and agents see when they hit one, and how to recover.
Limits#
Defaults on https://porch.okibi.ai. Self-hosted servers can change them (configuration); create_inbox and get_inbox report the values in effect.
| Limit | Default | When it's reached |
|---|---|---|
| Inbox lifetime | 24 hours (5 minutes to 7 days via ttl_minutes) |
The inbox and everything in it are deleted. Its URL returns 404. |
| Idle timeout | 4 hours without a keyed tool call | Same as above. |
| Requests per inbox | 1,000 | The oldest requests are dropped. |
| Body bytes per inbox | 8 MB | The oldest requests are dropped; the newest is always kept. |
| Request retention | 4 hours | The request disappears from listings and get_request. |
| Body size | 256 KB | The body is cut off and stored with body_truncated: true; the sender gets 413. |
| Wait time | 300 seconds per call | timed_out: true; call again. |
| Custom responses and approval links | 20 per inbox | set_response and create_approval_link return an error. |
| Custom response body | 64 KB | set_response returns an error. |
| Active inboxes | 1,000 across the server | create_inbox returns "Porch is at capacity". |
What senders see#
| Status | Meaning |
|---|---|
200 |
Recorded. The body is {"ok": true, "request_id": "req_N"} unless a custom response is set. |
204 |
CORS preflight answered (OPTIONS). |
404 {"ok": false, "error": "inbox_not_found"} |
The inbox doesn't exist, expired, or was deleted. Nothing was recorded. |
413 {"ok": false, "error": "payload_too_large"} |
The body was over the limit. The request was recorded with a truncated body. |
Approval links answer 400 for an invalid choice, 409 once the question is already answered, and 405 for methods other than GET and POST.
Tool errors#
Errors come back as tool results with isError: true and a message written for the agent.
| Message starts with | Cause | What to do |
|---|---|---|
| "That inbox_key is not valid, or its inbox has expired." | Wrong or mistyped key, or the inbox is gone. The two are deliberately indistinguishable. | Call create_inbox for a new inbox and key. |
| "Porch is at capacity" | The server has the maximum number of active inboxes. | Try again later, delete inboxes you no longer need, or self-host. |
| "No request req_N in this inbox" | The request expired, was dropped by a limit, or never existed. | Use list_requests to see what's stored. |
| "… is not a request id" | request_id or after isn't like req_12 (or start / latest for after). |
Use an id from a previous result. |
| "No approval link at …" | The path doesn't match a link in this inbox. |
Pass the path (or url) returned by create_approval_link. |
| "Porch does not let inboxes set the … header." | set_response tried to set a protected header. |
Remove that header. See Security. |
| "… is an approval link. Pick another path_prefix." | A custom response can't replace an approval link's path. | Use a different path_prefix. |
Protocol errors#
Malformed MCP requests get standard JSON-RPC errors from the transport, for example -32602 for invalid parameters (including an unknown skill URI in skills/get).