Limits, quotas, and errors

Webhook inboxes and email testing share one set of quotas per organization. Every error code the testing APIs return is in the error reference, with its fix.

Testing plans

Testing plan	Inboxes	Email domains	Custom domains	Retention ceiling (days)	Events per month
Free	3	1	No	3	300
Developer	10	1	No	7	3,000
Team	100	3	Yes	30	100,000
Business	500	10	Yes	90	300,000
Enterprise	Unlimited	Unlimited	Yes	365	Unlimited

Quotas apply per organization. Captured webhook events and received emails share the monthly event count. Testing plans are separate from monitoring plans.

An organization with no testing subscription is on Free. Your monitoring plan does not change these numbers.
Inboxes and email domains are counted across the whole organization, not per workspace. On Free, an email domain in one workspace blocks a second workspace from getting one. Disabled domains count.
Monthly events count every captured webhook request and every received or injected email. At the cap, webhook senders and inject get 403 and nothing is stored until the next month. Real mail sent over the cap can be accepted by the mail server and then dropped.
The monthly counter updates asynchronously. A burst that arrives at the cap can go slightly over it before refusals start.
Retention ceiling is the highest retentionDays an inbox accepts, and the default. DevHelm does not currently delete captured data on a schedule. See Security and data.

The limits on Rate limits belong to the monitoring plans, a separate ladder.

Rate and size limits

Limit	Value
Webhook ingest	120 requests per minute per sender IP, 600 per inbox, 1,200 per workspace
Wait calls	40 per minute per organization, shared by webhook and email waits
Wait timeout	`timeoutMs` defaults to 30000. Values above 120000 are treated as 120000
Request or email size	1 MiB. Larger bodies get `413`
Query string	8,192 characters
Headers	128 headers, 32 values per header, 8,192 characters per value
Body text in API responses	256 KB, then `bodyTruncated` is `true`. The raw download has every byte
Mock reply	Status 200–599, body up to 65,536 bytes, delay up to 30 seconds, up to 32 headers
Raw download links	Expire after 60 seconds

Also per inbox: maxEvents (1 to 100000, default 10000) caps stored events. When the inbox is full, the oldest event is dropped as a new one arrives.

How the limits apply

Ingest checks the per-IP window first, then resolves the token, then checks the per-inbox and per-workspace windows and the monthly cap. Requests to unknown tokens count against the IP window.
The wait limit counts calls, not time spent waiting. One 60-second wait costs the same as a 1-second one. Webhook and email waits share the 40 per minute across every workspace in the organization.
Size limits refuse the whole request. Nothing is stored or clipped to fit.
Email inject has no testing-specific rate limit. It counts against your organization’s general API rate limit and shares the size limits and the monthly cap.

Rate-limit responses

Every 429 carries Retry-After in seconds and the standard error body:

HTTP/1.1 429 Too Many Requests
Retry-After: 18
X-RateLimit-Limit: 40
X-RateLimit-Remaining: 0

{
  "status": 429,
  "code": "RATE_LIMITED",
  "message": "Rate limit exceeded. Retry after 1791377760.",
  "timestamp": 1791377742000,
  "requestId": "a1b2c3d4-5678-90ab-cdef-111111111111"
}

Neither SDK retries on its own. Wait Retry-After seconds, then call again. Retrying a wait with the same receivedAfter is safe: wait does not consume what it returns.

Error reference

Errors share one body shape. Branch on code; message is for people.

{
  "status": 408,
  "code": "WAIT_TIMEOUT",
  "message": "No matching inbound item arrived before timeout",
  "timestamp": 1791377739341,
  "requestId": null
}

Status	`code`	When	Fix
400	`WORKSPACE_REQUIRED`	A testing endpoint was called without `x-phelm-workspace-id`	Send the header, or set `DEVHELM_WORKSPACE_ID` for the CLI and SDKs
400	None guaranteed	Ingest rejected the request line: control characters in the method; a backslash, NUL, CR, LF, or malformed percent-escape in the path; or a path that resolves outside `/api/v1/ingest`	Send a plain path after the token. Nothing was stored
400	`INBOUND_INJECT_DOMAIN_DISABLED`	Inject into a domain whose status is `disabled`	Re-enable it: `PATCH` status `active` for an assigned domain, or verify a custom domain
403	`INBOUND_EVENTS_MONTHLY_LIMIT_REACHED`	The organization reached its monthly event cap. Webhook senders and inject get this	Wait for the next month or move to a larger testing plan. An inject accepted right at the cap can be dropped, and its wait then returns `408`
403	`INBOUND_WEBHOOK_INBOX_LIMIT_REACHED`	Creating an inbox past the plan’s inbox count	Delete unused inboxes in any workspace of the organization, or share one inbox per CI job with a path per test
403	`INBOUND_EMAIL_DOMAIN_LIMIT_REACHED`	Creating an email domain past the plan’s domain count, including from `address()`	Reuse the existing assigned domain. Disabled domains count, so delete one you no longer use
403	`INBOUND_CUSTOM_MX_PLAN_REQUIRED`	Creating a custom email domain below the Team testing plan	Use the assigned domain, or move to Team or above
403	`INBOUND_RETENTION_ABOVE_PLAN`	`retentionDays` above the plan ceiling on inbox create or update	Omit `retentionDays`, or send a value at or below the ceiling
404	`NOT_FOUND`, “Workspace doesn’t exist”	The workspace ID is wrong. The CLI and SDKs default to workspace `1` when `DEVHELM_WORKSPACE_ID` is unset	Set `DEVHELM_WORKSPACE_ID` to your workspace ID
404	`NOT_FOUND`, “Inbox not found”	Ingest to a token that never existed, belongs to a deleted inbox, or belongs to a disabled inbox. The three look the same	Check the URL, or set the inbox `status` back to `active`
408	`WAIT_TIMEOUT`	No matching event or message arrived before `timeoutMs`	Pass a `receivedAfter` captured before the trigger, check your filters, and raise `timeoutMs` (up to 120000)
413	`PAYLOAD_TOO_LARGE`	Body or email over 1 MiB, query over 8,192 characters, more than 128 headers, more than 32 values for one header, or a header value over 8,192 characters	Send less. Nothing was stored
429	`RATE_LIMITED`	An ingest window (IP, inbox, or workspace) or the 40 per minute wait limit was exceeded	Wait `Retry-After` seconds and retry. Spread waits across time in parallel CI
503	`SERVICE_UNAVAILABLE`	DevHelm could not store the body or queue it for processing	Retry the send. Nothing was stored

Field validation errors (for example a mock reply status outside 200–599) return 400 with a field-specific code and an errors[] entry naming the field. The 403 quota codes carry the same errors[] entry.

`408` that should have matched

A wait returns the oldest item with receivedAt at or after receivedAfter. The CLI and both SDKs default receivedAfter to the client clock when the call starts, so an item that arrived first is missed. Capture the time before you trigger the send and pass it:

const since = new Date().toISOString();
await triggerWebhook();
const event = await client.inboxes.wait(inboxId, { receivedAfter: since, timeoutMs: 30_000 });

from datetime import datetime, timezone

since = datetime.now(timezone.utc)
trigger_webhook()
event = client.inboxes.wait(inbox_id, received_after=since, timeout_ms=30_000)

Wait on a disabled inbox or domain is not an error. It times out with 408.

Errors in the SDKs and CLI

Status	TypeScript	Python
400, 408, 413	`DevhelmApiError`	`DevhelmApiError`
403	`DevhelmAuthError`	`DevhelmAuthError`
404	`DevhelmNotFoundError`	`DevhelmNotFoundError`
429	`DevhelmRateLimitError`, with `retryAfter`	`DevhelmRateLimitError`, with `retry_after`
503	`DevhelmServerError`	`DevhelmServerError`

Every class extends DevhelmApiError and carries status and code. A quota 403 is a DevhelmAuthError, so check code to tell it apart from a bad key. There is no timeout class: a 408 is a DevhelmApiError with code WAIT_TIMEOUT. Catch DevhelmRateLimitError before DevhelmApiError. The CLI prints the error class, message, and code, and exits non-zero (11 for a wait timeout):

DevhelmNotFoundError: Workspace doesn't exist
Code: NOT_FOUND

TypeScript errors and Python errors show the catch order in code.

Next steps

Testing in CI

Fit parallel jobs into the inbox cap and the wait budget.

Security and data

Who can read captured data and how to clean it up.

Wait for a webhook

Wait semantics, receivedAfter, and negative assertions.

Wait for an email

One address per test and repeat sends.

Getting Started

Testing

Monitoring as Code

Monitoring

Incidents

Alerting

Status Data

Platform

Common Patterns

Limits, quotas, and errors

Testing plans

Rate and size limits

How the limits apply

Rate-limit responses

Error reference

`408` that should have matched

Errors in the SDKs and CLI

Next steps

Testing in CI

Security and data

Wait for a webhook

Wait for an email

​Testing plans

​Rate and size limits

​How the limits apply

​Rate-limit responses

​Error reference

​408 that should have matched

​Errors in the SDKs and CLI

​Next steps

Testing in CI

Security and data

Wait for a webhook

Wait for an email

Testing plans

Rate and size limits

How the limits apply

Rate-limit responses

Error reference

`408` that should have matched

Errors in the SDKs and CLI

Next steps