Getting started

Errors

A failed request returns a 4xx or 5xx status and a JSON body with a stable `error_code`. Codes are part of the contract; messages are written for people and may change, so branch on the code.

The envelope

json
FieldMeaning
error_codeThe machine-readable reason. Always present.
messageA sentence for a person to read.
request_idThe request's id, also returned as the X-Request-ID header on every response. Include it when you contact support.
other fieldsContext for that code, such as fields on validation_error or retry_after_seconds on rate_limit_exceeded.

Handling errors

typescript

Retrying

  • 429 rate_limit_exceeded carries Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Wait, then retry.
  • 5xx responses can be retried with backoff. Send the same Idempotency-Key so a retry never repeats work that already happened.
  • Other 4xx codes describe the request itself; fix the request before sending it again.

Every code

The status shown is the code's usual status. A few codes are sent with a different status in specific places (for example limit_exceeded is 429 when the monthly API quota is spent), so read the status from the response.

error_codeStatus
access_key_not_found404
access_role_in_use409
access_role_name_taken409
access_role_not_found404
access_scope_unknown422
access_scopes_outside_role422
access_user_not_found404
access_would_lock_out409
account_no_longer_exists400
action_not_reversible409
action_undo_conflict409
action_undo_failed409
activity_cursor_invalid400
addon_already_exists409
addon_grant_not_grantable400
addon_not_found404
addon_not_synced409
admin_routes_require_jwt403
agent_goal_required400
agent_not_found404
agent_tool_config_not_found404
agent_worker_silent502
ai_provider_unavailable503
analytics_cursor_invalid400
answer_generate_too_many_asks422
answer_harvest_nothing_to_read422
answer_id_invalid400
answer_library_conflict_not_found404
answer_library_resolution_invalid422
answer_library_row_not_found404
answer_not_found404
answer_question_closed409
answer_question_needs_body422
answer_question_needs_stance422
answer_question_not_found404
answer_revision_not_found404
answer_run_failed500
api_key_expired401
api_key_invalid401
api_key_revoked401
api_key_test_mode_blocked403
api_scope_missing403
arthur_sales_input_too_long400
arthur_sales_rate_limited429
arthur_sales_unavailable503
asset_file_too_large413
asset_file_type_unsupported400
asset_storage_not_configured503
asset_upload_failed502
assignee_not_found404
assignment_not_found404
attachment_invalid400
attachment_limit_exceeded400
attachment_too_large413
attachment_type_unsupported415
audience_unknown400
authentication_required401
avatar_invalid_image400
avatar_too_large413
background_segment_not_found404
bid_sources_state_unknown404
billing_account_missing400
billing_idempotency_conflict409
billing_not_configured503
billing_test_run_busy409
billing_test_run_failed502
billing_test_run_finished409
billing_test_run_not_found404
blocking_orgs409
booking_not_cancellable409
booking_not_found404
booking_not_movable409
buyer_heading_not_found404
cannot_modify_self400
cannot_remove_self_as_admin400
category_not_found400
category_role_mismatch400
category_unknown400
chat_not_found404
checkout_session_failed502
checkout_session_not_found404
client_not_found404
cloud_connection_conflict409
cloud_consent_missing_scopes409
cloud_provider_init_failed503
cloud_provider_not_configured503
cloud_provider_unknown400
cloud_sharepoint_personal_account409
cloud_sharepoint_site_required409
cloud_sharepoint_sites_unavailable409
cloud_site_not_found404
cloud_sites_not_supported400
codefracture_not_configured503
codefracture_unreachable502
codefracture_workload_not_found404
compose_documents_unavailable422
compose_model_unavailable422
compose_no_grounding422
concurrent_limit_exceeded403
conflict409
connection_not_found404
content_not_editable409
content_part_not_found404
context_manifest_not_found404
context_not_found400
context_not_ready409
context_too_large400
context_view_not_enabled403
context_workspace_mismatch400
council_ideas_run_not_found404
council_models_invalid422
council_not_configured503
council_request_failed502
council_session_not_found404
council_turn_running409
council_unavailable503
coverage_cursor_invalid400
coverage_gate_blocked409
coverage_probe_not_running409
coverage_probe_state_unavailable503
coverage_target_claimed409
coverage_target_host_conflict409
coverage_target_invalid422
coverage_target_not_claimed409
coverage_target_source_taken409
coverage_target_source_unknown422
coverage_target_unknown404
coverage_target_wrong_status409
crawlfuse_event_invalid400
crawlfuse_not_configured503
crawlfuse_signature_invalid401
crawlfuse_unavailable503
credit_amount_invalid400
credit_package_not_found404
credit_purchase_not_available403
curate_invalid_split422
curate_unknown_key422
daily_spend_cap_reached429
darboux_event_invalid400
darboux_not_configured503
darboux_signature_invalid401
darboux_webhook_not_configured503
database_busy503
db_query_busy429
db_query_failed500
db_query_invalid400
db_query_timeout504
dc_artifact_not_found404
dc_event_rejected400
dc_event_type_unknown400
dc_payload_invalid400
dc_request_rejected400
dc_signature_invalid401
dc_workspace_not_found404
deepcontext_misconfigured503
deepcontext_unavailable503
default_org_not_member400
delete_failed400
demo_no_source_run409
demo_not_found404
demo_real_origin_protected403
demo_video_not_found404
demo_video_slug_conflict409
design_volume_not_document409
device_not_found404
document_asset_not_found404
document_asset_too_large413
document_asset_unsupported415
document_content_not_available404
document_content_not_editable409
document_dc_reject502
document_filename_invalid400
document_filetype_unsupported400
document_id_invalid400
document_indexing_failed500
document_invalid400
document_not_found404
document_processing_failed500
document_too_large413
document_upload_invalid400
document_write_target_required400
domain_already_configured409
domain_disposable400
domain_format_invalid400
domain_validation_failed400
drafting_step_needs_go422
driver_action_illegal_transition409
driver_action_not_found404
driver_actions_scope_required400
driver_daily_tick_cap429
driver_offer_constitutionally_locked422
driver_offer_not_found404
driver_prompt_no_seed422
driver_prompt_not_found404
driver_prompt_segment_exists409
driver_session_ended409
driver_session_not_found404
driver_session_tick_cap429
duration_not_offered422
edit_invalid400
email_already_verified400
email_auth_disabled403
email_change_target_in_use400
email_change_token_expired400
email_change_token_invalid400
email_change_unavailable400
email_required400
email_unchanged400
email_verification_required403
embedding_active_dropped409
embedding_dims_locked409
embedding_model_not_maintained409
embedding_switch_coverage_low409
event_type_not_found404
export_blocked_by_checks422
export_design_lost422
export_not_found404
export_nothing_picked422
export_page_limit_exceeded422
feature_already_exists409
feature_not_available403
feature_not_found404
file_empty400
finalize_failed500
forbidden403
form_box_invalid422
form_empty400
form_encrypted422
form_fact_unknown422
form_field_not_found404
form_format_unsupported415
form_not_found404
form_not_ready409
form_page_not_found404
form_representation_not_found404
form_revision_conflict409
form_too_large413
form_too_long422
form_type_unknown409
form_unreadable422
form_value_invalid422
form_value_personal403
form_value_too_long422
form_workspace_missing422
form_xfa_unsupported422
free_tool_input_too_large413
free_tool_rate_limited429
gateway_unavailable502
google_auth_disabled400
guidance_answer_empty422
guidance_choice_invalid422
guidance_question_duplicate409
guidance_question_not_found404
guidance_question_writing409
guidance_status_invalid422
guideline_not_found404
guideline_workspace_missing409
help_article_already_exists409
help_article_db_only400
help_article_invalid400
help_article_not_found404
help_ticket_invalid_action400
help_ticket_not_found404
idempotency_key_required400
idempotency_key_retry_exhausted409
idempotency_key_too_long400
import_conflict409
import_invalid400
import_job_not_found404
inbox_message_not_found404
inbox_pending_action_not_found404
inbox_sender_address_invalid422
inbox_sender_not_verified409
inbox_signature_invalid401
inbox_thread_not_found404
inbox_verify_token_invalid400
incorrect_password401
inject_no_answer409
insufficient_credits402
insufficient_credits_for_upload402
internal_access_required403
internal_error500
internal_key_on_public_route403
internal_scope_missing403
invalid_credentials401
invalid_email_format400
invalid_handoff_code400
invalid_method400
invalid_payload400
invalid_protocol400
invalid_provider400
invalid_refresh_token401
invalid_request400
invalid_role400
invalid_user_id400
invalid_uuid400
invitation_email_mismatch403
invitation_invalid400
invitation_not_found404
item_chat_failed500
item_details_mismatch422
item_documents_full400
item_link_invalid422
item_link_not_found404
item_not_found404
kickoff_nothing_to_do409
lake_not_configured503
lake_query_rejected400
lake_query_timeout504
lake_table_not_found404
last_organization409
layout_already_code409
layout_block_not_found404
layout_invalid422
layout_not_code409
layout_revision_conflict409
layout_revision_not_found404
lifetime_limit_exceeded403
lighthouse_event_invalid400
lighthouse_signature_invalid401
lighthouse_unavailable503
lighthouse_webhook_not_configured503
limit_exceeded403
live_mode_failed502
live_mode_not_allowed403
llm_config_guarded409
llm_config_invalid400
llm_config_not_found404
llm_config_validation_failed422
log_query_invalid400
magic_link_invalid400
marketing_asset_slot_unknown404
master_act_as_not_member403
master_act_as_user_unknown403
master_organization_required400
max_attached_docs_per_rfp_exceeded400
max_demos_per_founder_exceeded429
max_parallel_demo_creations_exceeded429
meetings_not_configured404
member_already_in_org409
member_conflict409
member_not_found404
member_role_invalid400
message_content_required400
message_not_found404
mfa_already_enabled400
mfa_invalid_code401
mfa_method_unknown400
mfa_not_enabled400
mfa_required_by_org403
mfa_session_invalid401
mfa_setup_not_initiated400
mfa_token_required401
model_route_invalid400
model_route_rejected422
model_slot_unknown404
monthly_quota_exceeded429
my_version_failed502
my_version_not_open409
name_empty400
name_too_long400
no_recovery_codes400
no_requirements409
not_demo_environment400
not_found404
not_member_of_organization403
notification_not_found404
oauth_domain_restricted403
oauth_exchange_failed401
oauth_init_failed500
oauth_provider_disabled503
oauth_provider_misconfigured503
observability_disabled503
oidc_id_token_invalid400
oidc_jwks_fetch_failed400
oidc_misconfigured400
oidc_no_email400
oidc_nonce_mismatch400
oidc_token_exchange_failed400
openobserve_unreachable502
operation_config_not_found404
operation_disabled403
operation_key_conflict409
operation_not_configured500
operation_unknown404
opportunity_submission_invalid422
organization_access_denied403
organization_already_exists409
organization_busy503
organization_deleted410
organization_id_invalid400
organization_not_found404
organization_slug_invalid400
outline_empty422
outline_not_ready409
outline_run_not_found404
outline_template_not_found404
outside_window422
override_not_found404
owner_required403
package_file_has_text409
package_file_not_found404
package_file_not_stored409
package_nothing_to_read409
package_read_in_progress409
packaging_invalid422
password_change_unavailable400
password_reset_expired400
password_reset_invalid400
password_reset_too_many_attempts400
password_strength_invalid400
password_unchanged400
past_proposal_guideline400
past_proposal_not_found404
payment_method_invalid400
payment_method_last_default409
plane_paused503
platform_admin_already409
platform_admin_not_found404
platform_admin_required403
platform_permission_required403
platform_proposal_limit_reached403
prepared_account_match_taken409
prepared_account_needs_match400
prepared_account_needs_organization400
prepared_account_not_found404
prepared_account_public_domain400
prepared_account_source_not_found404
price_invalid400
pricing_input_invalid400
probe_alert_state_invalid400
probe_dispatch_kind_invalid400
probe_filter_no_match400
probe_result_not_found404
probe_run_not_found404
probe_unknown404
probe_window_invalid400
procurement_candidate_unknown404
procurement_source_facts_missing422
procurement_source_link_unverified422
procurement_source_unknown404
programmatic_keys_require_api_key_auth403
prompt_already_exists409
prompt_invalid400
prompt_not_found404
prompt_version_not_found404
proposal_extraction_failed500
proposal_id_invalid400
proposal_not_found404
proposal_not_visible403
proposal_version_not_found404
proposal_version_pick_invalid422
prospect_not_found404
prospect_password_already_set400
prospect_token_expired400
pursuit_already_running409
pursuit_note_not_found404
quote_file_unreadable422
quote_line_not_found404
quote_not_found404
quote_read_failed502
quote_rfq_missing422
quote_supplier_not_found404
rate_limit_exceeded429
reaper_timeout500
reauth_method_unknown400
reauth_provider_mismatch400
reauth_required401
redis_unreachable502
reference_fetch_failed502
reference_url_invalid422
referenced_document_not_found404
referral_already_member409
referral_already_pending409
referral_already_used409
referral_channel_unavailable503
referral_code_inactive400
referral_expired400
referral_invalid400
referral_not_found404
referral_phone_invalid400
referral_revoked400
referral_self_referral400
refresh_token_missing401
regenerate_failed500
registration_disabled403
render_unavailable503
replay_bid_pursued409
replay_case_not_found404
replay_package_unread409
replay_target_not_internal403
request_id_invalid400
resource_not_found404
rfp_forbidden403
rolling_period_exceeded429
run_cost_cap_reached402
run_depth_exceeded409
run_not_awaiting_approval409
run_not_found404
run_open_limit_reached429
run_start_rate_limited429
saml_authentication_failed400
saml_config_incomplete400
saml_issuer_invalid400
saml_issuer_no_match400
saml_no_email400
saml_response_missing400
sandbox_no_org_membership404
sandbox_no_saved_payment_method409
sandbox_no_stripe_customer409
sandbox_session_not_found404
scenario_no_longer_registered409
scenario_overrides_invalid422
scenario_unknown400
scheduling_page_not_found404
scope_escalation_denied403
section_being_written409
section_criterion_invalid422
section_cycle409
section_depth_exceeded422
section_draft_not_found404
section_id_invalid400
section_ids_too_many400
section_limit_exceeded402
section_move_invalid422
section_no_proposal404
section_not_found404
section_piece_not_found404
section_revision_not_found404
section_run_not_found404
section_task_not_found404
session_id_invalid400
session_not_found404
setup_intent_failed502
showcase_not_found404
showcase_not_publishable409
showcase_rate_limited429
showcase_slug_taken409
signups_closed403
simulation_run_not_found404
slot_taken409
sole_owner409
sso_admin_required403
sso_auto_provisioning_disabled403
sso_connection_already_exists409
sso_connection_id_invalid400
sso_connection_no_longer_exists400
sso_connection_not_found404
sso_domain_already_configured409
sso_protocol_invalid400
sso_protocol_unsupported400
sso_state_expired400
sso_state_missing400
step_not_found404
storage_exceeded402
stripe_api_error502
stripe_customer_missing400
stripe_env_conflict409
stripe_env_not_configured503
stripe_error400
stripe_not_configured503
stripe_webhook_env_mismatch409
stripe_webhook_invalid400
stripe_webhook_not_configured500
stripe_webhook_signature_missing400
subcategory_not_found404
submission_answer_not_allowed422
submission_field_too_long400
submission_item_not_found404
submission_order_invalid422
submission_read_incomplete502
submission_rejected400
subscription_cancel_failed502
subscription_inactive403
subscription_needs_checkout409
subscription_no_active400
subscription_not_cancelling400
subscription_not_changeable409
subscription_not_pausable409
subscription_not_self_serve409
subscription_provider_failed502
suggestion_not_found404
surface_key_invalid401
sweep_invalid400
sweep_unknown404
tailstrike_event_invalid400
tailstrike_not_allowed403
tailstrike_not_configured503
tailstrike_request_failed502
tailstrike_signature_invalid401
tailstrike_task_not_found404
tailstrike_unavailable503
tailstrike_webhook_not_configured503
task_cell_invalid422
task_cell_not_found404
task_cell_taken409
task_item_not_found404
task_not_found404
task_person_result409
task_work_empty409
tenant_scope_missing500
tier_already_exists409
tier_has_no_pricing400
tier_limit_exceeded403
tier_not_found400
token_revoked401
topic_exists409
topic_not_found404
trace_id_invalid400
trace_not_found404
trace_query_invalid400
transcription_audio_too_large413
transcription_session_not_found404
transcription_unavailable503
transfer_target_not_member400
transfer_to_self400
trial_already_used409
trial_claim_not_found404
trial_invitation_exhausted409
trial_invitation_expired400
trial_invitation_not_found404
trial_invitation_revoked400
trial_link_in_use409
trial_not_live409
trial_offer_paid_start_needs_card400
trial_org_already_paid409
trial_org_unavailable400
trial_plan_locked409
trial_plan_unavailable400
trial_slug_taken409
trial_tier_locked409
trial_tier_unavailable400
trial_wrong_account409
trial_wrong_organization409
turn_interrupted503
turnstile_failed400
usage_event_not_found404
user_account_not_found404
user_already_exists409
user_not_found404
validation_error422
value_validation_failed400
verification_code_expired400
verification_code_invalid400
version_already_finalized409
version_id_invalid400
version_not_cancellable409
version_not_connected409
version_not_finalizable409
version_not_found404
version_not_viewing409
version_share_failed502
version_switch_failed502
versions_unavailable502
volume_label_taken409
volume_not_found404
volume_order_invalid422
volume_shape_mismatch422
volume_version_in_use409
volume_version_last409
volume_version_not_found404
volume_workbook_missing404
webhook_delivery_not_found404
webhook_event_not_subscribable403
webhook_event_not_system400
webhook_event_unknown400
webhook_not_found404
webhook_quota_exceeded402
webhook_signing_secret_invalid400
webhook_url_invalid400
workbook_batch_too_large413
workbook_cell_out_of_range422
workbook_column_not_found404
workbook_empty400
workbook_export_format409
workbook_format_unsupported415
workbook_header_out_of_range422
workbook_not_found404
workbook_nothing_to_fill422
workbook_nothing_to_write422
workbook_preview_unavailable409
workbook_sheet_not_found404
workbook_too_large413
workbook_unreadable422
workbook_window_invalid400
workbook_workspace_required400
worker_has_no_agent409
worker_internal_error500
workspace_access_denied403
workspace_already_exists409
workspace_default_required400
workspace_id_invalid400
workspace_id_required400
workspace_kind_invalid400
workspace_logo_invalid_image400
workspace_logo_too_large413
workspace_not_found404
workspace_org_mismatch403
workspace_slug_invalid400
wrong_auth_provider400