Error Dictionary
Due to the strict Zero-PII cryptographic mandates, debugging API failures can be complex. We return deterministic, canonical error codes so your middleware can automate retry logic or halt the ingestion pipeline.
HTTP Status Protocols
Marigold adheres to strict HTTP semantic conventions. Before parsing the JSON response body for a canonical error string, your HTTP client should respect the standard transport codes.
4xx Client Errors
The payload you sent is cryptographically invalid, violates JSON schema, or originates from a blocked IP. Do not retry these requests without modifying the payload or configuration.
429 Rate Limits
Your server is dispatching requests faster than your SLA tier allows. Implement exponential backoff and retry after the specified cool-down window.
5xx Server Errors
The algorithmic cluster encountered a math overflow (e.g. Z-Score matrix bounds exceeded). Highly anomalous but transient. Safe to retry with exponential backoff.
Canonical Error Codes
When a request fails, the response body will contain a code and a message field. Use the code for programmatic branching.
The AES-GCM authentication tag failed verification.
- Ensure your IV (Nonce) is exactly 12 bytes.
- Ensure your master key is exactly 32 bytes (256-bit).
- Ensure you appended the exact 16-byte Auth Tag to the end of the ciphertext before Base64 encoding.
details array in the response for the exact missing field (e.g. session_fingerprint is missing).anomaly_type string requested does not exist or has been deprecated. Call the /modules/list endpoint to view active modules.mg_live_ Bearer token has exceeded its 30-day lifecycle limit. Trigger your rotation cron job to fetch a new token via the /tokens/rotate endpoint using your administrative credential.Retry-After HTTP header (returns seconds) and implement a sleep/backoff loop before transmitting the next chunk.