Error codes

The error codes the console's API returns, with the HTTP status, whether a retry can help, and what to do.

When the console or an API call fails, the response carries a code. Find it below. Retry says whether trying again unchanged can succeed; when it says No, change what the last column names first.

For problems that show up before you get a code (the stack does not start, sign-in loops), see Troubleshooting.

Authentication

Code	Status	Retry	What to do
`account_signed_out`	409	No	Sign the account in on Accounts (SSO) or fix its access keys, then list again.
`authentication_required`	401	No	Authenticate via the provider login flow.
`aws_auth_failure`	401	No	See provider_error.code for the specific AWS-side error.
`aws_authentication_failed`	401	No	Refresh credentials/session and retry.
`aws_expired_token`	401	Yes	Re-run SSO device flow for the affected profile.
`aws_invalid_client_token`	401	No	Re-run SSO device flow or rotate static credentials.
`aws_signature_mismatch`	401	No	Refresh the affected account's credentials.
`session_expired_or_invalid`	401	No	Re-authenticate to obtain a new session.

Authorization

Code	Status	Retry	What to do
`audit_manage_forbidden`	403	No	Only admin users can manage log lifecycle settings.
`aws_access_denied`	403	No	Verify the role trust policy and AWS account ID.
`aws_kms_access`	403	No	Names the KMS key and action; allow it in both the key policy and the principal's IAM policy, or with a grant. See docs/aws/kms-customer-managed-keys.md.
`csrf_token_invalid`	403	No	Provide a valid X-CSRF-Token header for state-changing requests.
`insufficient_permissions`	403	No	Request a role/permission grant for the required operation.
`log_delivery_status_forbidden`	403	No	Sign in as an admin to read log delivery status.

Configuration

Code	Status	Retry	What to do
`calculator_snapshot_unavailable`	503	No	Reinstall Douklar, or rebuild src/core/s3_cost/prices.json with scripts/s3_price_snapshot.py.
`cli_import_policy_unavailable`	503	No	Fix the imports section of the app configuration (a mapping; trusted_signing_keys a mapping), then retry. Imports fail closed while the signature policy cannot be read.
`log_delivery_config_invalid`	500	No	Repair the saved log delivery destination; pending rows remain protected.

Conflict

Code	Status	Retry	What to do
`config_signature_conflict`	409	No	Load the latest checker policy, reconcile edits, and retry with its config_signature.
`idempotency_in_flight`	409	Yes	Retry with the same key once the in-flight request completes.
`idempotency_replay_unavailable`	409	No	The request already ran; read the resource's current state instead of retrying the key.
`s3_batch_job_already_running`	409	No	Resolve the stated conflict, then retry.
`s3_batch_retry_refused`	409	No	Fix the stated cause, or use New job to list both buckets again.
`s3_batch_start_refused`	409	No	Refresh the job; start only a job AWS reports as waiting, with an empty destination.
`s3_batch_submission_unavailable`	409	No	Reload Jobs and reconcile the recorded AWS submission. Do not submit again.

External service

Code	Status	Retry	What to do
`aws_s3_batch_error`	502	Yes	Retry the request. If the issue persists, inspect AWS service health and permissions.
`aws_sts_error`	502	Yes	Retry; if persistent, check STS endpoint reachability.
`s3_batch_provider_error`	502	Yes	Retry. If it persists, check AWS service health and the job's IAM role.

Infrastructure

Code	Status	Retry	What to do
`addon_config_unwritable`	503	Yes	Make the app configuration directory writable by the backend user, or set CONFIG_PATH to a writable location, then retry.
`checker_scope_unavailable`	503	Yes	Check the server log for the scope read failure (config files unreadable or the checker core failed to load), then retry.
`credential_store_unavailable`	503	Yes	Verify /app/.cache is writable; check AUTH_PROVIDER_KEY_FILE path.

Internal

Code	Status	Retry	What to do
`credential_store_error`	500	No	Check backend logs for the underlying error.
`credential_validation_internal_error`	500	No	Check backend logs.
`s3_batch_internal_error`	500	No	Unclassified failure on Douklar's side; quote the request id when reporting it.

Not found

Code	Status	Retry	What to do
`account_profile_not_found`	404	No	Verify the profile name matches config/simple-config.ini.
`credentials_not_found`	404	No	Run configure_credentials before validating.

Rate limit

Code	Status	Retry	What to do
`aws_rate_limited`	429	Yes	Back off and retry; see AWS throttling guidance.
`rate_limited`	429	Yes	Wait and retry the request.

Resource

Code	Status	Retry	What to do
`aws_resource_not_found`	404	No	Verify the referenced AWS resources and retry.
`plugin_not_in_catalog`	404	No	Refresh the catalog, or check PLUGIN_CATALOG_URL.
`s3_batch_job_not_found`	404	No	Check the identifier. Jobs are deleted 90 days after reaching a terminal state.
`s3_batch_resource_not_found`	404	No	Check the identifier. Jobs are deleted 90 days after reaching a terminal state.
`s3_batch_run_not_found`	404	No	Check the identifier. Jobs are deleted 90 days after reaching a terminal state.

Validation

Code	Status	Retry	What to do
`aws_invalid_request`	400	No	Correct the request parameters and retry.
`aws_region_required`	400	No	Pass an explicit region in the request payload.
`calculator_payload_too_large`	413	No	Send only the Calculator input fields; the body is limited to 16 KiB.
`cli_import_bundle_fields_required`	422	No	Attach both 'manifest' and 'bundle' multipart file fields.
`expected_account_id_invalid`	400	No	Confirm the 12-digit AWS account ID format.
`idempotency_key_invalid`	422	No	Send a UUID-grade Idempotency-Key (16-255 characters) and reuse it only for retries of the same request.
`idempotency_param_mismatch`	422	No	Reuse an Idempotency-Key only for retries of the same request; generate a new key for a different one.
`install_roles_invalid`	422	No	Fix the role-preset assignment payload per the error detail.
`invalid_account_check_interval`	422	No	Choose 0 (Off), 5, 15, 30, 60 or 240 minutes.
`invalid_mapping_scope`	422	No	Supply each mapping mode/profile scope only once per service.
`invalid_region`	400	No	Use a region such as us-east-1 or eu-west-1.
`missing_config_precondition`	422	No	Load the current checker policy and submit its config_signature with the write.
`plugin_not_implemented`	409	No	Upgrade Douklar to a build that ships this plugin.
`plugin_requires_newer_app`	409	No	Upgrade Douklar, then install the plugin.
`s3_batch_invalid_request`	422	No	Review request fields and manifest content, then retry.
`s3_batch_request_invalid`	422	No	Correct the reported field or prerequisite, then retry.
`service_not_installed`	409	No	Install the plugin from System › Installation › Plugins, then retry.

Count this visit?