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
`validation_failed`	Fix request shape, field values, schema, header, or multipart metadata.
`csv_parse_failed`	Fix the uploaded CSV and create or retry the upload.
`transient_intake_failure`	Retry when the upload still has a recoverable source.
`upload_source_expired`	Create a new upload because the original source is gone.

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.