invalid_request_error
genius_version_unsupported
Unsupported Genius-Version.
Meaning
The requested Genius API version is not supported.
Resolution
Use Genius-Version: 2026-04-01 or omit the header.
Docs route: /v1/errors/genius_version_unsupported
Genius error dictionary
Readable failures, not mystery failures.
Every public Genius error is structured. If a call fails, read error.code, then use this dictionary to decide whether to retry, back off, or ask for review.
HTTP 400
invalid_request_error
validation_error
Request validation failed.
Meaning
A required field is missing or malformed.
Resolution
Check the request body against /openapi.json and send all required fields.
Docs route: /v1/errors/validation_error
invalid_request_error
invalid_json
request body must be valid JSON
Meaning
The request body could not be parsed as JSON.
Resolution
Send valid JSON with the correct Content-Type header.
Docs route: /v1/errors/invalid_json
invalid_request_error
invalid_body
request body could not be read
Meaning
The request body could not be read or was empty when a payload was expected.
Resolution
Retry with a readable JSON request body.
Docs route: /v1/errors/invalid_body
authentication_error
authentication_required
authentication required
Meaning
The request did not include valid authenticated credentials.
Resolution
Authenticate with the current supported header-based auth before calling /v1 routes.
Docs route: /v1/errors/authentication_required
idempotency_error
idempotency_conflict
Idempotency key conflicts with a different request.
Meaning
The same Idempotency-Key was reused with a different request body on the same route.
Resolution
Reuse the same body with the same key, or generate a new Idempotency-Key.
Docs route: /v1/errors/idempotency_conflict
idempotency_error
idempotency_key_required
Idempotency-Key header is required for this mutation
Meaning
This mutation requires an Idempotency-Key header.
Resolution
Provide a unique Idempotency-Key header and retry the request.
Docs route: /v1/errors/idempotency_key_required
not_found_error
precommit_transaction_not_found
precommit transaction not found
Meaning
No governed communication transaction exists for the requested id.
Resolution
Check the transaction id and create or fetch a valid transaction first.
Docs route: /v1/errors/precommit_transaction_not_found
not_found_error
precommit_decision_not_found
precommit decision not found
Meaning
No persisted Genius decision exists for the requested id.
Resolution
Check the decision id and create or fetch a valid decision first.
Docs route: /v1/errors/precommit_decision_not_found
not_found_error
precommit_proof_packet_not_found
precommit proof packet not found
Meaning
No proof packet exists for the requested id.
Resolution
Check the proof packet id from a valid decision or transaction response.
Docs route: /v1/errors/precommit_proof_packet_not_found
service_unavailable_error
precommit_analysis_unavailable
precommit analysis failed closed before governance
Meaning
Genius could not complete the analysis path safely and failed closed.
Resolution
Retry later or route the communication to manual review.
Docs route: /v1/errors/precommit_analysis_unavailable
invalid_request_error
precommit_analysis_failed
precommit analysis could not be completed
Meaning
The input could not be converted into a governed decision safely.
Resolution
Review the request content and retry with a complete, valid communication payload.
Docs route: /v1/errors/precommit_analysis_failed
service_unavailable_error
internal_error
internal error
Meaning
Genius encountered an unexpected server-side failure.
Resolution
Retry later and use request_id or trace_id when contacting support.
Docs route: /v1/errors/internal_error
rate_limit_error
rate_limit_exceeded
Rate limit exceeded. Retry after the reset window.
Meaning
Too many Genius API calls were made within the current rate-limit window.
Resolution
Wait until the reset window or follow Retry-After before retrying.
Docs route: /v1/errors/rate_limit_exceeded
not_found_error
genius_error_code_not_found
genius error code not found
Meaning
The requested Genius error code is not present in the public dictionary.
Resolution
Consult /v1/errors for the current list of supported Genius error codes.
Docs route: /v1/errors/genius_error_code_not_found