Error envelope
#Errors return a code, a message, optional safe details, and a request ID. Keep the HTTP status and meta.requestId with your application's failure record. Database and provider internals are redacted from public server-error messages.
Handle a failure
#| Status | Next step |
|---|---|
| 400 / 415 | Correct the identifier, query, body, precondition, or JSON content type. |
| 401 | Check the key, expiry, revocation, and workspace API access. |
| 402 | Check the existing subscription, trial, or feature entitlement. |
| 403 | Check required scopes, forbidden actions, or a native plan-cap denial. |
| 404 | Check the operation and resource IDs within this workspace/project. |
| 405 | Use a supported method; Allow lists the methods. |
| 409 / 428 | Read current revision, lifecycle, approval, replay, or provider-precondition state before retrying. |
| 413 | Reduce the body to at most 1 MiB and respect field limits. |
| 422 | Check workflow eligibility; a writer brief cannot be approved for Webflow publishing. |
| 429 | Wait for Retry-After and use bounded backoff. |
| 500 / 502 / 503 | Retry a temporary failure cautiously; reconcile uncertain writes and retain the request ID. |
For a stale content edit, re-read and reconcile the document. Repeatedly sending the same stale revision does not resolve a conflict.
Request limits
#The API enforces 60 requests per minute per key and 300 per minute per workspace. Native feature-specific limits also remain in force. Rate-limit storage failures deny execution.
Key admission exposes RateLimit-Limit and RateLimit-Remaining. Throttled responses include Retry-After. The headers do not include a promised reset timestamp.
Use bounded backoff for temporary failures, preserve supported requestId replay identities, and poll long-running work at a reasonable interval. An accepted request is not proof that provider work completed.