Reference
Error codes
Every failure returns the same envelope:
Code
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. The statuses each endpoint can return are in the API reference.
Authentication and access
api_key_org_mismatchapi_key_org_not_provisionedauth_org_id_missingauth_user_id_missingauthentication_requiredinvalid_api_keyorganization_admin_permission_requiredpermission_requireduser_id_is_requireduser_membership_is_disableduser_not_org_member
Licensing
license_expiredlicense_missinglicense_unactivated
Credits and quota
credit_account_not_foundcredit_reservation_already_finalizedcredit_reservation_not_openinsufficient_creditsmissing_credit_reservationmonthly_quota_exceededquota_writes_platform_onlyreserved_credits_exhaustedstripe_credit_price_id_is_not_configured
Not found
agent_not_foundartefact_manifest_not_foundartefact_not_foundartifact_not_foundchat_not_foundcustom_role_not_founddocument_not_foundevidence_index_job_not_foundfile_content_not_foundfile_not_foundimport_not_foundjob_not_foundknowledgebase_not_foundmember_not_foundmessage_not_foundoperation_not_foundorganization_not_foundparse_artifact_not_foundschema_not_foundsegment_artifact_not_foundsheet_not_foundspreadsheet_artifact_not_foundsubfolder_not_found
Validation
apikey_is_requiredchatid_is_requiredchatid_messageid_and_type_are_requiredconfirmation_requireddocid_is_requireddocumentid_is_requiredduplicate_filenameduplicate_import_file_pathduplicate_knowledge_base_nameemail_is_requiredfile_id_is_requiredfile_ids_is_requiredfile_must_be_parsedfile_must_be_parsed_before_extractionfileids_must_be_uploaded_file_uuidsfilename_is_requiredid_is_requiredidempotency_key_requiredinvalid_a1_rangeinvalid_artefact_child_pathinvalid_artifact_keyinvalid_internal_tokeninvalid_licenseinvalid_org_roleinvalid_pii_extraction_requestinvalid_receiptinvalid_request_bodyinvalid_reservation_statusinvalid_schemainvalid_statuskeyid_is_requiredmode_must_be_reparse_or_deletemode_requiredmultipart_file_field_file_is_requiredmultipart_files_field_is_requiredname_and_companyfolder_are_requiredname_and_slug_are_requiredname_is_requiredoptions_must_be_valid_jsonorg_and_target_id_requiredorg_id_requiredorg_job_and_idempotency_key_requiredorgid_and_fileids_are_requiredorgid_and_jobid_are_requiredrelative_paths_count_mismatchrelative_paths_must_be_a_json_arrayschema_is_requiredsource_path_is_requiredsuggestion_fields_requiredunsupported_model
Models and processing
artifact_key_outside_organizationartifact_path_outside_rootartifact_unreadablemodel_provider_unavailablemodel_returned_unparseable_jsonprocessing_request_failedprocessing_service_unreachablesplit_download_requires_pdfsplit_model_unavailable
Other
agent_access_deniedcould_not_create_auth_userdefault_knowledge_base_creation_failedfailed_to_create_evidence_index_jobfailed_to_save_edit_proposalfile_access_deniedfile_has_active_jobfile_has_no_current_versionfile_ids_not_in_knowledge_basefile_not_deletedguest_mode_disabledguest_sign_up_did_not_return_a_user_idjob_is_not_activeknowledge_base_access_deniedmissing_license_tokenmissing_organization_contextmissing_receiptmissing_stripe_signatureno_queueable_import_decisionsno_updatable_fieldsorg_admin_cannot_be_disabledstripe_price_id_not_configuredstripe_webhook_is_not_configured
Last modified on