Errors and limits
Responses include a requestId. Save it with failures when asking Maglev for help. Do not include your API key.
Check record ownership and key rotation when a record becomes unavailable after changing credentials. Live work belongs to the organization; sandbox work belongs to the individual key.
{"error":{"code":"version_conflict","message":"Interview changed. Reload it before replying."},"requestId":"req_example"}Recovery
Section titled “Recovery”| HTTP status | Meaning | Next step |
|---|---|---|
| 400 | Invalid JSON, field or required header | Fix the named input. Validation responses can include field details. |
| 401 | Invalid, expired or revoked key | Reconnect a valid key. Live-key issuance requires a session. |
| 403 | Insufficient access | Check organization ownership or reviewer access; do not switch identities to bypass it. |
| 404 | Endpoint/record unavailable in this scope | Check the URL and ID. Another key’s sandbox records are not accessible. |
| 409 | Interview version, publication or idempotency conflict | Reload the record; reuse an idempotency key only with its original body. |
| 422 | Missing facts, turn limit or quantity below MOQ | Resolve the specified requirement before retrying. |
| 429 | Quota reached | Respect Retry-After; do not create keys to bypass quotas. |
| 500 | Request could not complete | Check saved state, retain the request ID, then retry appropriately. |
| 502 | Action generation failed | Preserve the action ID from error details, retrieve its saved state, and review the error before requesting new work. |
| 503 | Interviewer could not complete a turn | Reload the interview, retain previous answers, and retry only if necessary. |
Local CLI input errors
Section titled “Local CLI input errors”invalid_encoding means the selected file or pipe is not valid UTF-8. invalid_number means a JSON number would overflow, underflow to zero or exceed the supported safe integer range. Both exit with code 2 before sending an HTTP request. Correct the source export; keep long identifiers as strings. See CLI input handling.
Current limits
Section titled “Current limits”| Limit | Sandbox | Live |
|---|---|---|
| Requests per key per minute | 60 | 60 |
| Requests per key per day | 1,000 | 20,000 |
| New interviews per scope per day | 5 per key | 30 per organization |
| AI turns per scope per day | 20 per key | 100 per organization |
| Saved turns per interview | 16 | 16 |
| Key lifetime | 24 hours | 90 days |
Public sandbox issuance is limited to five keys per IP per day. Additional shared IP/global sandbox AI limits apply. Rate counters use time windows; daily limits are not a promise of a reset at local midnight.
Idempotency and 409 conflicts
Section titled “Idempotency and 409 conflicts”POST /run and POST /projects/{id}/actions require an Idempotency-Key header of 8 to 120 letters, numbers, underscores or hyphens. No other write shares this guarantee.
| You did this | Result |
|---|---|
| Retried the identical body with its original key | The existing record, replayed: true for a run. Nothing reruns |
| Reused a key with a changed body | HTTP 409. The earlier record is preserved |
| Reused a key for a new revision, same input | The old record, even after the project’s intake changed. It is not recomputed |
| Sent a new request without a new key | Whatever that key already holds. Every new piece of work needs a new key |
A replay can return HTTP 200 with status running or failed. HTTP 200 does not mean new work completed; read the action’s state before deciding. If an action stays running, keep its ID and ask Maglev to investigate rather than creating duplicate work.
These writes are not idempotent and need a different recovery:
| Write | Recover by |
|---|---|
POST /projects |
List recent projects before creating another |
POST /interviews |
Read the local receipt; interview_receipt_unsaved carries interviewId. There is no list-interviews API |
PATCH /projects/{id} |
Reload the brief and resend its contextVersion as expectedContextVersion |
| Engineering preview | Record the returned previewId and requestId; a dropped response may leave a saved preview |
| Delivery approval | Read get_delivery. Recover only the existing approved dispatch inside its retry window |
409 also covers a version conflict on an interview or a changed delivery review. Reload the record and show a fresh review before approving; never refresh a digest automatically after a conflict.
The CLI and the MCP connector never retry writes automatically. CLI exit code 4 is a version or idempotency conflict.
Interview fallback
Section titled “Interview fallback”engine: guided explicitly identifies deterministic extraction during provider unavailability or configured guided mode. It is not an AI-generated conversation. Follow the returned labeled format and supply only the person’s actual facts.
Connection failures
Section titled “Connection failures”A timeout tells you the response did not arrive, not whether a write was committed. Retrieve the saved run, interview or project action before deciding what to do next. For an action whose response never arrived, filter the action list by project ID. The CLI defaults to four minutes for action requests and permits up to five minutes with --timeout 300000. The CLI rejects authenticated redirects and non-JSON responses with a structured error.
CLI 0.3.1 preserves API error.details on stderr. For an action-generation failure, use error.details.actionId with maglev actions get ACTION_ID --json. A response interrupted after headers is a network_error; its request ID is kept when the server supplied one. HTML or an unexpected JSON shape produces invalid_response. Neither case automatically retries a write.