Errors

Every error has a stable code, a message and a hint written for the agent: what to do next.

REST answers with the HTTP status of the code and this body (details only when there are details):

{ "error": { "code": "SCOPE_MISSING", "message": "This key lacks scope 'send'.", "hint": "…", "details": { "scope": "send" } } }

An MCP tool answers with isError: true and one text block, CODE: message hint. A missing or revoked key and a rate limit are refused before any tool runs: HTTP 401 or 429 with a JSON-RPC error whose message is the same text.

Code	HTTP	Message	Hint
UNAUTHENTICATED	401	Missing or invalid API key.	Pass the project key as Authorization: Bearer brk_live_…. Run npx brynth init to get one.
KEY_REVOKED	401	This API key has been revoked.	This key was revoked. Ask the project owner for a new key.
SCOPE_MISSING	403	This key lacks a required scope.	Create a key with that scope (POST /v1/keys, needs admin).
VALIDATION_FAILED	400	The request is invalid.	Fix the listed fields and retry.
NOT_FOUND	404	Not found.
SLUG_TAKEN	409	This slug is already taken.	Choose another slug or omit it to get one derived from the name.
LOGIN_NOT_VERIFIED	409	The sign-in link has not been confirmed yet.	The user has not clicked the email link yet. Keep polling /v1/auth/poll.
LOGIN_EXPIRED	410	This sign-in has expired.	Start again with /v1/auth/start.
LOGIN_CONSUMED	409	This sign-in was already used.	This login was already used to create a project. Start a new login.
PROJECT_LIMIT_REACHED	409	This account already has the maximum number of projects.	Reuse an existing project: run npx brynth status or connect it with BRYNTH_KEY. Contact support to raise the limit.
LAST_ADMIN_KEY	409	This is the last active admin key of the project.	Create another admin key before revoking this one.
RATE_LIMITED	429	Too many requests.	Wait retry_after seconds.
EMAIL_DELIVERY_FAILED	502	The sign-in email could not be sent.	Retry in a minute. If it keeps failing, contact support.
INGRESS_SIGNATURE_INVALID	401	The webhook signature is missing or invalid.	Signature missing or wrong. Check the source secret set with source_add.
PAYLOAD_TOO_LARGE	413	The request body is too large.	Webhook bodies are limited to 5 MB.
SOURCE_NAME_TAKEN	409	A source with this name already exists in the project.	Choose another name.
EMAIL_SOURCE_EXISTS	409	The project already has an email source.	The project already has its email address; see source_list.
EVENT_NOT_CLAIMABLE	409	The event cannot be claimed or changed in its current state.	The event is already claimed or closed. Call inbox_list for pending events.
EVENT_ROUTED	409	The event is delivered by a routing rule.	This event is delivered by callback, not by pull.
LEASE_NOT_HELD	409	Another key holds the lease on this event.	Another key holds this event. Claim a pending event instead.
LEASE_EXPIRED	409	The lease on this event has expired.	Your lease expired and the event went back to the queue. Claim it again with inbox_claim.
TOO_MANY_WAITS	429	Too many concurrent waits.	Too many concurrent inbox_wait (10 per key, 25 per project). Wait for one to return.
CALLBACK_URL_REJECTED	400	The callback URL is not allowed.	Use an https URL on a public address.
KEY_LIMIT_REACHED	409	The project has reached its limit of active keys.	The project has 20 active keys. Revoke one first.
CHANNEL_NOT_VERIFIED	409	An approver is not an active channel of this project.	An approver is not an active channel. Call channel_list, or channel_add("telegram") and ask the user to complete verification.
CHANNEL_ADDRESS_REJECTED	400	This address cannot be used as a channel.	Use a valid email outside the Brynth inbound domain.
CHANNEL_EXISTS	409	This address is already a channel of the project.	This address is already a channel; see channel_list.
CHANNEL_OWNER_PROTECTED	409	The owner's channel cannot be removed.	The owner's channel cannot be removed.
CHANNEL_KIND_UNAVAILABLE	400	This channel kind is not available on this server.	This channel kind is not configured on this server. Use email.
POLICY_INVALID	400	The policy document is invalid.	Fix the field at path and call policy_set again.
TOO_MANY_PENDING_REQUESTS	429	The project has too many pending requests.	50 requests are pending. Wait for answers or let old ones expire.
CALLBACK_SECRET_MISSING	409	The project has no request callback secret.	Create the project's callback secret with POST /v1/request-callback-secret, or omit callback_url.
DETAILS_REQUIRED	400	A high-risk request needs details.	Put in details what you will do, why, what it touches (resources, people, amounts) and whether it can be undone. If the action is not high risk, lower risk.
QUOTA_EXCEEDED	409	The project disk is full.	The project disk is full (limit, used). Delete keys or files you no longer need, then retry.
POLICY_DENIED	403	A project policy denies this action.	A project policy denies this action (rule). Ask the user to change the policy with policy_set if it should be allowed.
APPROVAL_NOT_APPLICABLE	409	The approval does not apply to this call.	The approval does not match this call: it must be an approved file_url request for the same file and expires_in, not yet used, redeemed with the API key that asked for it within 24 hours of the decision. Call file_url without approval to ask again.
UPLOAD_INCOMPLETE	409	The upload is incomplete.	The upload is missing or its size differs from the declared one. PUT the file to upload_url with upload_headers, then call file_put with complete again.
UPLOAD_LIMIT	429	Too many open uploads at this path.	3 presigned uploads are already open at this path. Finish one with complete, or wait for its upload_url to expire (15 minutes after upload), then call file_put with upload again.
PATH_RESERVED	400	This key or path is reserved.	Keys under state/ are managed by state_save; paths under evt_…/ are inbound attachments and read-only.
SEND_LIMIT_REACHED	429	The project reached its sending limit.	The project reached its sending limit (limit, window). Retry after retry_after, or send to fewer recipients.
SEND_BLOCKED	403	Sending is blocked for this project.	Sending is blocked for this project after too many bounces or complaints, or by the operator. Tell the user; only Brynth support can unblock it.
EMAIL_SOURCE_REQUIRED	409	The project has no active email source.	The project has no active email address, so replies would be lost. Add one with source_add (type email), then retry.
INTERNAL	500	Internal error.	Retry later. Quote the X-Request-Id header if it keeps failing.