Visão geral
Trate erros em duas camadas: primeiro o status HTTP e depoiserror.code quando existir. Nomes de campos e códigos não são traduzidos porque fazem parte do contrato da API.
Formato da resposta
{
"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.