API errors and rate limits
Wirechunk returns structured problem responses for failed requests. Use the HTTP status for the broad category and the code field for the specific condition.
Problem response
A validation error can look like this:
{
"type": "about:blank",
"title": "validation failed",
"status": 422,
"code": "validation_failed",
"detail": "Correct the page fields.",
"resolution": "Correct the indicated fields and try again.",
"errors": [{ "field": "path", "message": "Use a unique full page path." }]
}
The detail above illustrates the structure; individual errors supply their own messages. errors and retryAfter are optional. Log the code and relevant operation context without exposing credentials or private form contents.
Common statuses
| Status | What to do |
|---|---|
| 401 | Sign in, renew a valid OAuth session, or reconnect a revoked agent as directed. |
| 402 | Review site service and the required billing step. |
| 403 | Check email verification, site/account permission, and browser origin. |
| 404 | Confirm the resource ID and the selected Draft or Published version. |
| 409 | Read current state and resolve the conflict before retrying. |
| 413 | Reduce the request or file size. |
| 422 | Correct the identified fields or cross-record validation errors. |
| 429 | Follow the retry guidance and reduce request frequency. |
| 500 or 503 | Inspect the response and retry cautiously when the failure is temporary. |
Limits
Limits vary by operation. The management server has a default request-size limit of about 2 MB; upload routes have their own bounds. Public asset uploads support up to 10 MiB. The built-in assistant currently limits a user to 500 requests in a rolling 24-hour period.
A response can include retryAfter and a Retry-After header. Honor that delay when present. Other errors may give a human-readable retry instruction. Use bounded retries with backoff rather than repeatedly submitting the same failure.
Retry writes carefully
An interrupted response does not always mean nothing happened. Read the current record or operation status before repeating a write. Use expectedVersionId to detect content conflicts. Continue an existing billing request or transfer rather than creating another one.
Public form submissions support an idempotency key. Reuse the same key for a retry of the same data, and use a new key for a genuinely new inquiry.