Limits and errors
Errors
Errors are JSON: {"error": "Message not found."}, plus a stable code where a client should react programmatically. The SDKs raise HeraldError with status, code, messageId and retryAfter.
| Status | Meaning |
|---|---|
| 400 | Invalid input; the message names the field. |
| 401 | Missing, invalid or revoked token. |
| 403 | Missing scope, a human-only endpoint, a token without an end-to-end key (E2EE_TOKEN_UNKEYED), or an account without access (NOT_ADMITTED). |
| 404 | Not found, or not visible to this token. |
| 408 | SDKs only: a client wait timed out. The request is still open; resume with wait. |
| 409 | Conflict: a changed idempotent retry, an already answered request, a task no longer queued; E2EE_UNKEYED when the account has no keys yet; E2EE_RECIPIENT_UNKEYED when a recipient has no key; E2EE_ID_TAKEN when an encrypted record reuses an ID; E2EE_SEALED_REQUIRED for plaintext content. |
| 410 | Expired, or already consumed (secrets are collected once). |
| 413 | Body too large, or storage full. |
| 429 | Rate limited (RATE_LIMITED, with Retry-After), or the monthly allowance or pending-request limit is full. |
| 503 | Sign-in is not open (SIGN_IN_DISABLED), or a temporary outage. |
The SDKs retry network errors and 5xx for reads and keyed writes, and wait out 429s that carry Retry-After (up to 60 seconds).
CLI exit codes
| Code | Meaning |
|---|---|
| 0 | Success, or the request was answered |
| 1 | Error, including a wait that timed out |
| 2 | Usage error |
| 3 | The request expired |
| 4 | The request was cancelled |
Limits
| Limit | Value |
|---|---|
| Requests | 600 per minute per token or session |
| JSON body | 128 KiB |
| Title / body | 180 / 50,000 characters |
| Form fields | 30 per form |
| Actions / blocks | 8 / 10 per message |
| Attachments | 10 per message, 100 MB each |
| Secrets | 16,000 bytes; collected once within 15 minutes |
| Request deadline | 24 hours |
| Live sockets | 20 per account |
| Connections | 50 per account |
| Destinations | 100 per connection |
| Task logs | 4,096 characters per chunk, 32,000 per task |
Monthly resolutions, storage, retention and pending requests depend on your plan; see Pricing. A resolution is an answered request, a delivered message or an acknowledged task; reads, retries and logs are free. Usage resets each UTC month.