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

# Errores y códigos

> Estados HTTP, códigos de negocio y manejo para la API Alforse.

## Resumen

Maneja los errores en dos capas: primero el estado HTTP y luego `error.code` cuando exista. Los nombres de campos y códigos no se traducen porque son contrato de API.

## Formato de respuesta

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

## HTTP

| Estado | Significado                                                                                                      | Acción recomendada                                             |
| ------ | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| 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.                                                                                     | Uso 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.                                                                              | Reintento idempotent reads with backoff.                       |

## Plan y cuota

| Código                         | Manejo                                                                            |
| ------------------------------ | --------------------------------------------------------------------------------- |
| `PLAN_CONTRACT_LIMIT_EXCEEDED` | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `PLAN_SEAT_LIMIT_EXCEEDED`     | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `PLAN_STORAGE_LIMIT_EXCEEDED`  | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `PLAN_FEATURE_NOT_ENABLED`     | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `PLAN_SUBSCRIPTION_REQUIRED`   | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `PLAN_SUBSCRIPTION_INACTIVE`   | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `PLAN_NOT_AVAILABLE`           | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |

## Archivo y subida

| Código                            | Manejo                                                                            |
| --------------------------------- | --------------------------------------------------------------------------------- |
| `FILE_NAME_INVALID`               | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `FILE_SIZE_EMPTY`                 | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `FILE_TOO_LARGE`                  | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `FILE_CONTENT_TYPE_NOT_ALLOWED`   | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `FILE_EXTENSION_NOT_ALLOWED`      | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `FILE_KIND_NOT_ALLOWED`           | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `FILE_REF_INVALID`                | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `FILE_KIND_MISMATCH`              | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `FILE_SCAN_NOT_CLEAN`             | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `FILE_SCAN_REQUEST_FAILED`        | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `FILE_BINDING_CONTEXT_MISMATCH`   | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `UPLOAD_OBJECT_KEY_MISMATCH`      | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `UPLOAD_OBJECT_NOT_FOUND`         | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `UPLOAD_OBJECT_SIZE_MISMATCH`     | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `UPLOAD_OBJECT_TYPE_MISMATCH`     | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `UPLOAD_OBJECT_CHECKSUM_MISMATCH` | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `UPLOAD_TOKEN_INVALID`            | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `UPLOAD_TOKEN_EXPIRED`            | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `UPLOAD_METADATA_MISMATCH`        | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |

## Importe y factura

| Código                          | Manejo                                                                            |
| ------------------------------- | --------------------------------------------------------------------------------- |
| `AMOUNT_REQUIRED`               | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `AMOUNT_INVALID`                | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `AMOUNT_UNSAFE_NUMBER`          | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `AMOUNT_OUT_OF_RANGE`           | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `AMOUNT_SCALE_INVALID`          | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `UNSUPPORTED_CURRENCY`          | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `INVOICE_AMOUNT_EXCEEDS_TARGET` | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |

## Contrato y workflow

| Código                               | Manejo                                                                            |
| ------------------------------------ | --------------------------------------------------------------------------------- |
| `OWNER_SCOPE_RESTRICTED`             | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `ASSIGNEE_NOT_ACTIVE_TENANT_MEMBER`  | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `SUBJECT_NOT_FOUND`                  | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `CONTRACT_TYPE_NOT_CONFIGURED`       | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `LIFECYCLE_STAGE_NOT_CONFIGURED`     | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `LIFECYCLE_TEMPLATE_NOT_AVAILABLE`   | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `DYNAMIC_FIELDS_INVALID`             | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `DYNAMIC_FIELD_UNKNOWN`              | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `DYNAMIC_FIELD_REQUIRED`             | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `DYNAMIC_FIELD_TYPE_INVALID`         | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `DYNAMIC_FIELD_OPTION_INVALID`       | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `CONTRACT_PDF_REQUIRED`              | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `REQUIRED_FIELDS_MISSING`            | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `CONTRACT_CORE_FIELDS_LOCKED`        | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `WORKFLOW_FIELDS_REQUIRE_TRANSITION` | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `WORKFLOW_REQUIRED_FIELDS_MISSING`   | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `WORKFLOW_REQUIRED_EVIDENCE_MISSING` | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `WORKFLOW_AI_REVIEW_PENDING`         | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `WORKFLOW_FULFILLMENT_OPEN`          | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `WORKFLOW_RECEIVABLES_OPEN`          | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |
| `WORKFLOW_NOTE_REQUIRED`             | Usa el estado HTTP, message y details para mostrar qué corregir; luego reintenta. |

## Reintento

* Reintentar GET idempotentes y lecturas 503 con backoff.
* En POST, PATCH y DELETE, comprobar estado actual tras timeout o 5xx antes de reintentar.
* No reintentar sin cambios 400, 401, 403, 404, 409 o 422.