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

# Erros e códigos

> Status HTTP, códigos de negócio e tratamento da API Alforse.

## Visão geral

Trate erros em duas camadas: primeiro o status HTTP e depois `error.code` quando existir. Nomes de campos e códigos não são traduzidos porque fazem parte do contrato da API.

## Formato da resposta

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

## HTTP

| Status | Significado                                                                                                      | Ação 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.                                                                              | Repetição idempotent reads with backoff.                       |

## Plano e cota

| Código                         | Tratamento                                                                                |
| ------------------------------ | ----------------------------------------------------------------------------------------- |
| `PLAN_CONTRACT_LIMIT_EXCEEDED` | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `PLAN_SEAT_LIMIT_EXCEEDED`     | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `PLAN_STORAGE_LIMIT_EXCEEDED`  | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `PLAN_FEATURE_NOT_ENABLED`     | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `PLAN_SUBSCRIPTION_REQUIRED`   | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `PLAN_SUBSCRIPTION_INACTIVE`   | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `PLAN_NOT_AVAILABLE`           | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |

## Arquivo e envio

| Código                            | Tratamento                                                                                |
| --------------------------------- | ----------------------------------------------------------------------------------------- |
| `FILE_NAME_INVALID`               | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `FILE_SIZE_EMPTY`                 | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `FILE_TOO_LARGE`                  | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `FILE_CONTENT_TYPE_NOT_ALLOWED`   | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `FILE_EXTENSION_NOT_ALLOWED`      | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `FILE_KIND_NOT_ALLOWED`           | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `FILE_REF_INVALID`                | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `FILE_KIND_MISMATCH`              | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `FILE_SCAN_NOT_CLEAN`             | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `FILE_SCAN_REQUEST_FAILED`        | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `FILE_BINDING_CONTEXT_MISMATCH`   | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `UPLOAD_OBJECT_KEY_MISMATCH`      | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `UPLOAD_OBJECT_NOT_FOUND`         | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `UPLOAD_OBJECT_SIZE_MISMATCH`     | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `UPLOAD_OBJECT_TYPE_MISMATCH`     | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `UPLOAD_OBJECT_CHECKSUM_MISMATCH` | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `UPLOAD_TOKEN_INVALID`            | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `UPLOAD_TOKEN_EXPIRED`            | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `UPLOAD_METADATA_MISMATCH`        | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |

## Valor e fatura

| Código                          | Tratamento                                                                                |
| ------------------------------- | ----------------------------------------------------------------------------------------- |
| `AMOUNT_REQUIRED`               | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `AMOUNT_INVALID`                | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `AMOUNT_UNSAFE_NUMBER`          | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `AMOUNT_OUT_OF_RANGE`           | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `AMOUNT_SCALE_INVALID`          | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `UNSUPPORTED_CURRENCY`          | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `INVOICE_AMOUNT_EXCEEDS_TARGET` | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |

## Contrato e workflow

| Código                               | Tratamento                                                                                |
| ------------------------------------ | ----------------------------------------------------------------------------------------- |
| `OWNER_SCOPE_RESTRICTED`             | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `ASSIGNEE_NOT_ACTIVE_TENANT_MEMBER`  | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `SUBJECT_NOT_FOUND`                  | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `CONTRACT_TYPE_NOT_CONFIGURED`       | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `LIFECYCLE_STAGE_NOT_CONFIGURED`     | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `LIFECYCLE_TEMPLATE_NOT_AVAILABLE`   | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `DYNAMIC_FIELDS_INVALID`             | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `DYNAMIC_FIELD_UNKNOWN`              | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `DYNAMIC_FIELD_REQUIRED`             | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `DYNAMIC_FIELD_TYPE_INVALID`         | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `DYNAMIC_FIELD_OPTION_INVALID`       | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `CONTRACT_PDF_REQUIRED`              | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `REQUIRED_FIELDS_MISSING`            | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `CONTRACT_CORE_FIELDS_LOCKED`        | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `WORKFLOW_FIELDS_REQUIRE_TRANSITION` | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `WORKFLOW_REQUIRED_FIELDS_MISSING`   | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `WORKFLOW_REQUIRED_EVIDENCE_MISSING` | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `WORKFLOW_AI_REVIEW_PENDING`         | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `WORKFLOW_FULFILLMENT_OPEN`          | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `WORKFLOW_RECEIVABLES_OPEN`          | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |
| `WORKFLOW_NOTE_REQUIRED`             | Uso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente. |

## Repetição

* Repetir GET idempotente e leituras 503 com backoff.
* Em POST, PATCH e DELETE, verificar estado atual após timeout ou 5xx antes de repetir.
* Não repetir sem mudanças 400, 401, 403, 404, 409 ou 422.