# 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](/docs/douklar/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. |

Source: https://douklar.app/docs/douklar/error-codes (Douklar docs, last checked 2026-10-18)