API errors | everyn

Everyn API errors use one public envelope so clients can classify failures consistently. The code tells you what failed, requestId lets an operator find the request, and docsUrl points to the most specific recovery guidance available.

Error envelope

Public envelope:

{
  "error": {
    "status": 422,
    "code": "validation_failed",
    "message": "Request validation failed.",
    "requestId": "req_...",
    "docsUrl": "https://www.geteveryn.com/docs/errors/validation_failed",
    "fieldErrors": [
      {
        "source": { "pointer": "/outputSchema/columns/0/name" },
        "code": "invalid_column_name",
        "message": "Column names must match ^[a-z][a-z0-9_]*$."
      }
    ]
  }
}

Recovery matrix:

Status and code	Typical cause	Client behavior
`400 validation_failed`	Malformed JSON, multipart metadata, invalid cursor, or missing protocol header.	Fix the request before retrying.
`401 authentication_failed`	Missing, malformed, unknown, revoked, or expired bearer credential.	Replace the credential.
`403 authorization_failed`	Valid credential without required scope or role.	Use a permitted credential.
`404 not_found`	Resource does not exist for this organization.	Verify the ID and organization context.
`409 idempotency_conflict`	Same idempotency key with a different create request.	Reuse the original request or create a new key for new work.
`409 export_not_ready`	Download requested before export is ready.	Poll the export resource until `downloadReady` is true.
`410 export_expired`	Export artifact is no longer downloadable.	Create a new export.
`413 validation_failed`	Multipart CSV is over the direct upload limit.	Reduce or split the file below 25 MiB.

Specific public error pages live under Error reference. The generated endpoint response contracts live under API reference.