# Error codes

Every failure returns the same envelope:

```json
{ "error": "Knowledge base access denied", "code": "knowledge_base_access_denied" }
```

**Branch on `code`.** It is stable. `error` is a human-readable sentence and
may be reworded in any release — matching on it will break.

Some responses add `message` with extra detail.

This page is generated from the API's own registry, so it cannot fall behind
the code. 128 codes today.

## Deciding what to do

The HTTP status tells you whether the call is worth sending again.

| Status | What to do |
|---|---|
| `400`, `409`, `422` | Do not retry. The request body or the resource state is wrong, and the same call will fail the same way. |
| `401` | Re-authenticate. The key is missing, wrong, revoked or expired; an organization admin issues a new one. |
| `402` | Stop and top up. Credits or the monthly quota ran out, or the deployment's licence is restricted. Nothing was queued. |
| `403` | Do not retry. The caller lacks the permission or the resource grant. |
| `404` | Do not retry. Wrong id, another organization's id, or soft-deleted. |
| `502`, `503` | Retry with backoff. An upstream model provider was unavailable — the request itself was fine. |

The DocAI API has no rate limit: no endpoint declares a `429` status, and
there is no rate-limit code in the error registry.

The codes you meet first are in the [quickstart](/quickstart). The statuses
each endpoint can return are in the [API reference](/api).

## Authentication and access

- `api_key_org_mismatch`
- `api_key_org_not_provisioned`
- `auth_org_id_missing`
- `auth_user_id_missing`
- `authentication_required`
- `invalid_api_key`
- `organization_admin_permission_required`
- `permission_required`
- `user_id_is_required`
- `user_membership_is_disabled`
- `user_not_org_member`

## Licensing

- `license_expired`
- `license_missing`
- `license_unactivated`

## Credits and quota

- `credit_account_not_found`
- `credit_reservation_already_finalized`
- `credit_reservation_not_open`
- `insufficient_credits`
- `missing_credit_reservation`
- `monthly_quota_exceeded`
- `quota_writes_platform_only`
- `reserved_credits_exhausted`
- `stripe_credit_price_id_is_not_configured`

## Not found

- `agent_not_found`
- `artefact_manifest_not_found`
- `artefact_not_found`
- `artifact_not_found`
- `chat_not_found`
- `custom_role_not_found`
- `document_not_found`
- `evidence_index_job_not_found`
- `file_content_not_found`
- `file_not_found`
- `import_not_found`
- `job_not_found`
- `knowledgebase_not_found`
- `member_not_found`
- `message_not_found`
- `operation_not_found`
- `organization_not_found`
- `parse_artifact_not_found`
- `schema_not_found`
- `segment_artifact_not_found`
- `sheet_not_found`
- `spreadsheet_artifact_not_found`
- `subfolder_not_found`

## Validation

- `apikey_is_required`
- `chatid_is_required`
- `chatid_messageid_and_type_are_required`
- `confirmation_required`
- `docid_is_required`
- `documentid_is_required`
- `duplicate_filename`
- `duplicate_import_file_path`
- `duplicate_knowledge_base_name`
- `email_is_required`
- `file_id_is_required`
- `file_ids_is_required`
- `file_must_be_parsed`
- `file_must_be_parsed_before_extraction`
- `fileids_must_be_uploaded_file_uuids`
- `filename_is_required`
- `id_is_required`
- `idempotency_key_required`
- `invalid_a1_range`
- `invalid_artefact_child_path`
- `invalid_artifact_key`
- `invalid_internal_token`
- `invalid_license`
- `invalid_org_role`
- `invalid_pii_extraction_request`
- `invalid_receipt`
- `invalid_request_body`
- `invalid_reservation_status`
- `invalid_schema`
- `invalid_status`
- `keyid_is_required`
- `mode_must_be_reparse_or_delete`
- `mode_required`
- `multipart_file_field_file_is_required`
- `multipart_files_field_is_required`
- `name_and_companyfolder_are_required`
- `name_and_slug_are_required`
- `name_is_required`
- `options_must_be_valid_json`
- `org_and_target_id_required`
- `org_id_required`
- `org_job_and_idempotency_key_required`
- `orgid_and_fileids_are_required`
- `orgid_and_jobid_are_required`
- `relative_paths_count_mismatch`
- `relative_paths_must_be_a_json_array`
- `schema_is_required`
- `source_path_is_required`
- `suggestion_fields_required`
- `unsupported_model`

## Models and processing

- `artifact_key_outside_organization`
- `artifact_path_outside_root`
- `artifact_unreadable`
- `model_provider_unavailable`
- `model_returned_unparseable_json`
- `processing_request_failed`
- `processing_service_unreachable`
- `split_download_requires_pdf`
- `split_model_unavailable`

## Other

- `agent_access_denied`
- `could_not_create_auth_user`
- `default_knowledge_base_creation_failed`
- `failed_to_create_evidence_index_job`
- `failed_to_save_edit_proposal`
- `file_access_denied`
- `file_has_active_job`
- `file_has_no_current_version`
- `file_ids_not_in_knowledge_base`
- `file_not_deleted`
- `guest_mode_disabled`
- `guest_sign_up_did_not_return_a_user_id`
- `job_is_not_active`
- `knowledge_base_access_denied`
- `missing_license_token`
- `missing_organization_context`
- `missing_receipt`
- `missing_stripe_signature`
- `no_queueable_import_decisions`
- `no_updatable_fields`
- `org_admin_cannot_be_disabled`
- `stripe_price_id_not_configured`
- `stripe_webhook_is_not_configured`