Error reference

Everyn errors are meant to be recoverable and linkable. Public API errors include a stable code, a readable message, a requestId, a docsUrl, and optional fieldErrors. Dataset upload failures also expose public-safe failure metadata on the resource itself.

Use this section as the recovery hub. Use API errors when you need the exact HTTP envelope shape. Use specific error-code pages when an error includes a docsUrl.

Reading and recovering from errors

How to read an Everyn error

Field	Meaning	What to do
`status`	HTTP status category.	Decide whether this is validation, auth, state, retry, or internal.
`code`	Stable machine-readable error.	Open the matching docs page when available.
`message`	Readable summary.	Quote or paraphrase without losing the code.
`requestId`	Support and trace identifier.	Preserve it in bug reports or support summaries.
`docsUrl`	Canonical recovery page.	Read it before recommending a fix.
`fieldErrors`	Field, header, parameter, or form-specific issues.	Name the exact affected field and expected shape.

Recovery decision table

Situation	Retry?	Better next action
Invalid JSON, missing required field, bad column name, unsupported model.	No.	Fix the request or job spec, then send a new request.
Missing, malformed, revoked, or expired credential.	No.	Replace the credential.
Valid principal lacks required scope or role.	No.	Use a credential with the required permission.
Cross-organization or missing resource.	No blind retry.	Verify the ID belongs to the authenticated organization.
Idempotency fingerprint conflict.	No with the same key.	Reuse the key only for the exact same request, or send a new key.
Export not ready.	Poll.	Read the export until it is ready before downloading.
Transient intake failure.	Maybe.	Retry only when the upload source still exists and the error is marked retryable.
Internal or upstream outage.	After recovery.	Preserve `requestId` and retry after the service recovers.

Specific error pages

Code	Typical next step
`artifact_expired`	Recreate the export or artifact and use the new download URL.
`authentication_failed`	Replace the missing, malformed, revoked, or expired credential.
`authorization_failed`	Use a credential with the required scope, role, or organization access.
`browser_auth_disabled`	No client-side retry; browser sign-in is unconfigured for this deployment.
`billing_checkout_preparing`	Wait for `retryAfterMilliseconds` and repeat the exact request with the same idempotency key.
`billing_checkout_terminal_recovery`	Start a new paid Checkout attempt; include `requestId` when contacting support.
`conflict`	Refresh the resource state and retry only when the conflicting state changes.
`csv_parse_failed`	Fix the uploaded CSV and create or retry the upload.
`dataset_artifact_unavailable`	Not retryable; re-upload or replace the dataset (`suggestedAction: replace_dataset`).
`dataset_identity_index_unavailable`	Retryable; re-run upload processing without re-uploading the file.
`dataset_intake_state_invalid`	Retry upload processing when the stored processing state can be rebuilt.
`dataset_intake_unavailable`	Retry dataset intake later.
`dataset_registration_failed`	Create a new upload or contact support with the upload ID.
`export_expired`	Create a new export.
`export_failed`	Inspect the export failure and create a new export after the cause is fixed.
`export_not_ready`	Poll the export until it is ready before downloading.
`file_too_large_for_multipart`	Use a smaller CSV or a future resumable upload path.
`idempotency_conflict`	Reuse idempotency keys only for identical requests or send a new key.
`internal_error`	Preserve `requestId` and retry after the service recovers.
`invalid_state`	Refresh the resource and choose an operation valid for its current state.
`invitation_already_accepted`	Sign in with the accepted account or request a new invitation.
`invitation_conflict`	Review the invitation state and issue a new invitation if needed.
`invitation_email_mismatch`	Sign in with the invited email address.
`invitation_expired`	Request or send a new invitation.
`invitation_revoked`	Request or send a new active invitation.
`last_owner_conflict`	Add or promote another owner before removing the current one.
`no_retryable_rows`	Select failed, flagged, or retryable skipped rows before creating a retry run.
`not_found`	Verify the ID, path, and authenticated organization.
`query_result_not_ready`	Poll while nonterminal; read the result on `succeeded`, inspect the failure on `failed`.
`rate_limited`	Wait and retry with backoff.
`run_already_terminal`	Create a retry or follow-up run instead of mutating the terminal run.
`run_analysis_snapshot_not_ready`	Poll while `details.status` is `queued` or `processing`; stop on `failed`.
`run_not_terminal`	Wait until the run reaches a terminal state before using terminal-only operations.
`run_paused`	Resume or cancel the paused run before continuing.
`service_unavailable`	Retry after the dependency or readiness issue clears.
`session_expired`	Sign in again to establish a fresh browser session.
`transient_intake_failure`	Retry when the upload still has a recoverable source.
`unauthenticated`	Send the user through sign-in; expected for an anonymous browser.
`upload_already_completed`	Use the completed dataset instead of retrying the upload.
`upload_expired`	Create a new upload.
`upload_processing`	Wait for current processing to finish.
`upload_processing_failed`	Inspect the safe failure metadata and retry only when retryable.
`upload_source_expired`	Create a new upload because the original source is gone.
`upload_source_metadata_mismatch`	Recreate the upload with matching file metadata.
`upload_source_size_mismatch`	Recreate the upload with the correct file size.
`upload_source_unavailable`	Retry processing later if the source can still be read.
`validation_failed`	Fix request shape, field values, schema, header, or multipart metadata.

Relationship to API errors

This page answers "what should the client do next?" The API errors page answers "what does the HTTP error envelope look like?"

Safety rules

Never expose API keys, webhook secrets, auth headers, secret hashes, object-store pointers, signed URLs, stack traces, source rows, or generated outputs in an error summary.
Do not infer whether a resource exists in another organization.
Do not retry non-retryable validation, authentication, or authorization errors.
Keep requestId visible for support escalation.