Errors and retries

Interpret API errors and decide when a request is safe to retry.

Error shape

{
  "error": {
    "code": "invalid_request",
    "message": "A novel name of 1-300 characters is required."
  }
}

Use the machine-readable code for program logic and keep the message for diagnostics. Messages may become more specific without a version change.

HTTP statuses

Status	Meaning	Retry?
`400`	Malformed body, header, or destination	Fix request
`401`	Missing or invalid API key	Fix credentials
`403`	Integration or capability disabled	Contact Genesis
`409`	Identity or idempotency conflict	Investigate; do not blind retry
`413`	Payload too large	Reduce payload
`415`	Content type is not JSON	Fix header/body
`422`	Semantically invalid fields	Fix fields
`429`	Rate limit exceeded	Retry with backoff
`500`	Temporary server failure	Retry with backoff

Retry policy

Retry network timeouts, 429, and temporary 5xx responses with exponential backoff and jitter. Always reuse the same idempotency key and body. Stop after a bounded number of attempts and alert an operator.

Do not automatically retry validation, authentication, permission, or conflict responses.

Support diagnostics

When contacting Genesis, provide the integration slug, endpoint, UTC time, HTTP status, error code, and idempotency key. Do not include the API key, raw onboarding URL, JWE, signing private key, password, or unnecessary personal information.