> ## 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.

# Erreurs et codes

> Statuts HTTP, codes métier et traitement pour l’API Alforse.

## Vue d’ensemble

Traitez les erreurs en deux niveaux : d’abord le statut HTTP, puis `error.code` lorsqu’il est présent. Les noms de champs et les codes restent inchangés car ils font partie du contrat API.

## Format de réponse

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

## HTTP

| Statut | Signification                                                                                                    | Action recommandée                                             |
| ------ | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| 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.                                                                                     | Usage 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.                                                                              | Nouvelle tentative idempotent reads with backoff.              |

## Plan et quota

| Code                           | Traitement                                                                                          |
| ------------------------------ | --------------------------------------------------------------------------------------------------- |
| `PLAN_CONTRACT_LIMIT_EXCEEDED` | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `PLAN_SEAT_LIMIT_EXCEEDED`     | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `PLAN_STORAGE_LIMIT_EXCEEDED`  | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `PLAN_FEATURE_NOT_ENABLED`     | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `PLAN_SUBSCRIPTION_REQUIRED`   | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `PLAN_SUBSCRIPTION_INACTIVE`   | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `PLAN_NOT_AVAILABLE`           | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |

## Fichier et téléversement

| Code                              | Traitement                                                                                          |
| --------------------------------- | --------------------------------------------------------------------------------------------------- |
| `FILE_NAME_INVALID`               | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `FILE_SIZE_EMPTY`                 | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `FILE_TOO_LARGE`                  | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `FILE_CONTENT_TYPE_NOT_ALLOWED`   | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `FILE_EXTENSION_NOT_ALLOWED`      | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `FILE_KIND_NOT_ALLOWED`           | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `FILE_REF_INVALID`                | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `FILE_KIND_MISMATCH`              | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `FILE_SCAN_NOT_CLEAN`             | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `FILE_SCAN_REQUEST_FAILED`        | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `FILE_BINDING_CONTEXT_MISMATCH`   | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `UPLOAD_OBJECT_KEY_MISMATCH`      | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `UPLOAD_OBJECT_NOT_FOUND`         | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `UPLOAD_OBJECT_SIZE_MISMATCH`     | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `UPLOAD_OBJECT_TYPE_MISMATCH`     | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `UPLOAD_OBJECT_CHECKSUM_MISMATCH` | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `UPLOAD_TOKEN_INVALID`            | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `UPLOAD_TOKEN_EXPIRED`            | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `UPLOAD_METADATA_MISMATCH`        | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |

## Montant et facture

| Code                            | Traitement                                                                                          |
| ------------------------------- | --------------------------------------------------------------------------------------------------- |
| `AMOUNT_REQUIRED`               | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `AMOUNT_INVALID`                | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `AMOUNT_UNSAFE_NUMBER`          | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `AMOUNT_OUT_OF_RANGE`           | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `AMOUNT_SCALE_INVALID`          | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `UNSUPPORTED_CURRENCY`          | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `INVOICE_AMOUNT_EXCEEDS_TARGET` | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |

## Contrat et workflow

| Code                                 | Traitement                                                                                          |
| ------------------------------------ | --------------------------------------------------------------------------------------------------- |
| `OWNER_SCOPE_RESTRICTED`             | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `ASSIGNEE_NOT_ACTIVE_TENANT_MEMBER`  | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `SUBJECT_NOT_FOUND`                  | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `CONTRACT_TYPE_NOT_CONFIGURED`       | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `LIFECYCLE_STAGE_NOT_CONFIGURED`     | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `LIFECYCLE_TEMPLATE_NOT_AVAILABLE`   | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `DYNAMIC_FIELDS_INVALID`             | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `DYNAMIC_FIELD_UNKNOWN`              | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `DYNAMIC_FIELD_REQUIRED`             | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `DYNAMIC_FIELD_TYPE_INVALID`         | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `DYNAMIC_FIELD_OPTION_INVALID`       | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `CONTRACT_PDF_REQUIRED`              | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `REQUIRED_FIELDS_MISSING`            | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `CONTRACT_CORE_FIELDS_LOCKED`        | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `WORKFLOW_FIELDS_REQUIRE_TRANSITION` | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `WORKFLOW_REQUIRED_FIELDS_MISSING`   | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `WORKFLOW_REQUIRED_EVIDENCE_MISSING` | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `WORKFLOW_AI_REVIEW_PENDING`         | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `WORKFLOW_FULFILLMENT_OPEN`          | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `WORKFLOW_RECEIVABLES_OPEN`          | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |
| `WORKFLOW_NOTE_REQUIRED`             | Utilisez le statut HTTP, message et details pour afficher la correction nécessaire, puis réessayez. |

## Nouvelle tentative

* Réessayer les GET idempotents et lectures 503 avec backoff.
* Pour POST, PATCH et DELETE, vérifier l’état courant après timeout ou 5xx avant de réessayer.
* Ne pas réessayer inchangé après 400, 401, 403, 404, 409 ou 422.