Mavera DocsReference
Checking your Mavera sessionLoading workspace audiences and API keys…
Checking…Use or share this pageSend the page itself, print it, or open its complete context in your AI workspace.
Errors, limits & headers
Error envelope, rate limits, response headers.
The envelope
{ "ok": true, "data": { … }, "meta": { "tool": "…", "estimateCredits": N } }
{ "ok": false, "error": { "code": "…", "message": "…" } }Error codes
| Status | Code | Meaning & fix |
|---|---|---|
| 401 | UNAUTHORIZED | Missing/invalid/revoked x-api-key. Mint or rotate the key. |
| 402 | PAYMENT_REQUIRED | Out of credits this period. Upgrade plan or add credits. |
| 403 | FORBIDDEN | Not an admin for this workspace (members/billing/keys). |
| 404 | UNKNOWN_TOOL / UNKNOWN_SURFACE / NOT_FOUND | No such tool/surface/run. |
| 422 | VALIDATION_ERROR | Body didn't match the tool's JSON-Schema. The message lists the issues. |
| 429 | RATE_LIMITED | Too many requests. Honor Retry-After. |
| 400 | TOOL_ERROR / BAD_REQUEST | The tool ran but failed, or a malformed request. |
| 500 | INTERNAL | Unexpected server error. |
Response headers
| Header | On | Meaning |
|---|---|---|
X-RateLimit-Limit | every call | Requests allowed per window. |
X-RateLimit-Remaining | every call | Requests left in the current window. |
X-RateLimit-Reset | every call | Unix seconds when the window resets. |
Retry-After | 429 | Seconds to wait before retrying. |
X-Credits-Used | metered calls | Credits this request consumed. |
X-Tokens-Total | metered calls | Input + output tokens this request. |
Rate limits
Per-key sliding window — defaults to 120 requests / 60s (configurable via API_RATE_LIMIT / API_RATE_WINDOW_MS; set the limit to 0 to disable). Public discovery endpoints are rate-limited by IP.
Retry guidance
- 429 — back off for
Retry-Afterseconds, then retry. Use jittered exponential backoff for bursts. - 402 — don't retry; top up credits or upgrade.
- 5xx — safe to retry idempotent reads; for tool invocations, check the result before re-running anything irreversible.
- 422 — fix the body; retrying unchanged won't help. Pull the schema from
GET /api/v1/tools/{name}.