> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alforse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fehlercodes

> HTTP-Status, Business-Fehlercodes und Umgang für die Alforse API.

## Überblick

Fehler werden in zwei Ebenen behandelt: zuerst der HTTP-Status, danach – falls vorhanden – `error.code`. Feldnamen und Code-Bezeichner bleiben unverändert, weil sie Teil des API-Vertrags sind.

## Antwortformat

```json theme={null}
{
  "error": {
    "code": "PLAN_FEATURE_NOT_ENABLED",
    "message": "Feature is not enabled for this plan",
    "details": { "feature": "workflowAutomation" }
  }
}
```

## HTTP

| Status | Bedeutung                                                                                                        | Empfehlung                                                     |
| ------ | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| 400    | Invalid JSON, field, option, human-verification, file input, or money validation problem.                        | Fix request data before retrying.                              |
| 401    | Missing/invalid token, bad credentials, MFA failure, revoked refresh token, or inactive tenant/user/member/role. | Re-authenticate or restore access.                             |
| 403    | Authenticated but blocked by permission, scope, plan entitlement, capacity, origin, or signature.                | Grant access, upgrade plan, or fix request integrity settings. |
| 404    | Resource missing, deleted, outside tenant, or hidden by scope.                                                   | Check id and caller scope.                                     |
| 409    | Unique value already exists.                                                                                     | Einsatz another value or load existing resource.               |
| 422    | Domain rule violation such as workflow gate, dynamic field rule, import limit, or required evidence.             | Resolve the domain condition and retry.                        |
| 429    | Rate limit exceeded.                                                                                             | Back off before retrying.                                      |
| 500    | Unhandled server error.                                                                                          | Check whether writes succeeded before retrying.                |
| 503    | Dependency temporarily unavailable.                                                                              | Wiederholen idempotent reads with backoff.                     |

## Plan und Quota

| Code                           | Umgang                                                                                                    |
| ------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `PLAN_CONTRACT_LIMIT_EXCEEDED` | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `PLAN_SEAT_LIMIT_EXCEEDED`     | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `PLAN_STORAGE_LIMIT_EXCEEDED`  | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `PLAN_FEATURE_NOT_ENABLED`     | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `PLAN_SUBSCRIPTION_REQUIRED`   | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `PLAN_SUBSCRIPTION_INACTIVE`   | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `PLAN_NOT_AVAILABLE`           | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |

## Datei und Upload

| Code                              | Umgang                                                                                                    |
| --------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `FILE_NAME_INVALID`               | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `FILE_SIZE_EMPTY`                 | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `FILE_TOO_LARGE`                  | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `FILE_CONTENT_TYPE_NOT_ALLOWED`   | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `FILE_EXTENSION_NOT_ALLOWED`      | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `FILE_KIND_NOT_ALLOWED`           | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `FILE_REF_INVALID`                | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `FILE_KIND_MISMATCH`              | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `FILE_SCAN_NOT_CLEAN`             | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `FILE_SCAN_REQUEST_FAILED`        | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `FILE_BINDING_CONTEXT_MISMATCH`   | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `UPLOAD_OBJECT_KEY_MISMATCH`      | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `UPLOAD_OBJECT_NOT_FOUND`         | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `UPLOAD_OBJECT_SIZE_MISMATCH`     | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `UPLOAD_OBJECT_TYPE_MISMATCH`     | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `UPLOAD_OBJECT_CHECKSUM_MISMATCH` | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `UPLOAD_TOKEN_INVALID`            | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `UPLOAD_TOKEN_EXPIRED`            | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `UPLOAD_METADATA_MISMATCH`        | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |

## Betrag und Rechnung

| Code                            | Umgang                                                                                                    |
| ------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `AMOUNT_REQUIRED`               | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `AMOUNT_INVALID`                | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `AMOUNT_UNSAFE_NUMBER`          | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `AMOUNT_OUT_OF_RANGE`           | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `AMOUNT_SCALE_INVALID`          | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `UNSUPPORTED_CURRENCY`          | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `INVOICE_AMOUNT_EXCEEDS_TARGET` | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |

## Vertrag und Workflow

| Code                                 | Umgang                                                                                                    |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `OWNER_SCOPE_RESTRICTED`             | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `ASSIGNEE_NOT_ACTIVE_TENANT_MEMBER`  | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `SUBJECT_NOT_FOUND`                  | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `CONTRACT_TYPE_NOT_CONFIGURED`       | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `LIFECYCLE_STAGE_NOT_CONFIGURED`     | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `LIFECYCLE_TEMPLATE_NOT_AVAILABLE`   | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `DYNAMIC_FIELDS_INVALID`             | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `DYNAMIC_FIELD_UNKNOWN`              | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `DYNAMIC_FIELD_REQUIRED`             | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `DYNAMIC_FIELD_TYPE_INVALID`         | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `DYNAMIC_FIELD_OPTION_INVALID`       | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `CONTRACT_PDF_REQUIRED`              | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `REQUIRED_FIELDS_MISSING`            | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `CONTRACT_CORE_FIELDS_LOCKED`        | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `WORKFLOW_FIELDS_REQUIRE_TRANSITION` | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `WORKFLOW_REQUIRED_FIELDS_MISSING`   | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `WORKFLOW_REQUIRED_EVIDENCE_MISSING` | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `WORKFLOW_AI_REVIEW_PENDING`         | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `WORKFLOW_FULFILLMENT_OPEN`          | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `WORKFLOW_RECEIVABLES_OPEN`          | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |
| `WORKFLOW_NOTE_REQUIRED`             | Nutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen. |

## Wiederholen

* Idempotente GETs und 503-Lesezugriffe mit Backoff erneut versuchen.
* Bei POST, PATCH und DELETE nach Timeout oder 5xx zuerst den aktuellen Ressourcenstatus prüfen.
* 400, 401, 403, 404, 409 und 422 nicht unverändert erneut senden.