Errors and limits

What This Does

This page explains the boring-but-important parts: errors, limits, and retries.

Rate Limits

Tool connector routes use this limit:

60 requests per minute per token/client

Some website widget routes have their own limits. The public developer docs focus on tool connector routes.

Common HTTP Errors

Status	Meaning	What to do
`401`	Token missing, malformed, revoked, or invalid	Check the bearer token and rotate it if needed
`403`	Token is valid but lacks the needed capability	Enable the capability or use a different connector
`404`	Item or message is not available to this connector	Check organization ownership and message source
`409`	A duplicate request is still running, or a retry key was reused with different request content	Retry the same request later, or create a new key for genuinely new work
`422`	Request shape is invalid	Fix the payload fields
`429`	Rate limit hit	Back off and retry later

Safe Retries

For external replies, use a safe retry key called idempotency_key.

For memory saves, use idempotency_key when your app may retry the same write.

Good retry behavior:

Generate one key for the work item.
Reuse that key if the network fails.
Do not generate a new key for the same work item unless you really want a new request.

Bombyx stores a normalized request fingerprint with an external reply. An exact completed retry returns the original response and marks grounding.idempotent_replay as true. Reusing the key or external message ID with different content returns 409.

Validation Notes

External assistant message text can be up to 20,000 characters.

Thread history can include up to 20 items. Bombyx currently uses the latest 10 history items when building the internal message body.

Memory search limit can be 1 to 50 results.