Saltar para o conteúdo principal

​
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

{
  "error": {
    "code": "PLAN_FEATURE_NOT_ENABLED",
    "message": "Feature is not enabled for this plan",
    "details": { "feature": "workflowAutomation" }
  }
}

​
HTTP

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

​
Plano e cota

CódigoTratamento
PLAN_CONTRACT_LIMIT_EXCEEDEDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
PLAN_SEAT_LIMIT_EXCEEDEDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
PLAN_STORAGE_LIMIT_EXCEEDEDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
PLAN_FEATURE_NOT_ENABLEDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
PLAN_SUBSCRIPTION_REQUIREDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
PLAN_SUBSCRIPTION_INACTIVEUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
PLAN_NOT_AVAILABLEUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.

​
Arquivo e envio

CódigoTratamento
FILE_NAME_INVALIDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
FILE_SIZE_EMPTYUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
FILE_TOO_LARGEUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
FILE_CONTENT_TYPE_NOT_ALLOWEDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
FILE_EXTENSION_NOT_ALLOWEDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
FILE_KIND_NOT_ALLOWEDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
FILE_REF_INVALIDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
FILE_KIND_MISMATCHUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
FILE_SCAN_NOT_CLEANUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
FILE_SCAN_REQUEST_FAILEDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
FILE_BINDING_CONTEXT_MISMATCHUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
UPLOAD_OBJECT_KEY_MISMATCHUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
UPLOAD_OBJECT_NOT_FOUNDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
UPLOAD_OBJECT_SIZE_MISMATCHUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
UPLOAD_OBJECT_TYPE_MISMATCHUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
UPLOAD_OBJECT_CHECKSUM_MISMATCHUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
UPLOAD_TOKEN_INVALIDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
UPLOAD_TOKEN_EXPIREDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
UPLOAD_METADATA_MISMATCHUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.

​
Valor e fatura

CódigoTratamento
AMOUNT_REQUIREDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
AMOUNT_INVALIDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
AMOUNT_UNSAFE_NUMBERUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
AMOUNT_OUT_OF_RANGEUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
AMOUNT_SCALE_INVALIDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
UNSUPPORTED_CURRENCYUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
INVOICE_AMOUNT_EXCEEDS_TARGETUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.

​
Contrato e workflow

CódigoTratamento
OWNER_SCOPE_RESTRICTEDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
ASSIGNEE_NOT_ACTIVE_TENANT_MEMBERUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
SUBJECT_NOT_FOUNDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
CONTRACT_TYPE_NOT_CONFIGUREDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
LIFECYCLE_STAGE_NOT_CONFIGUREDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
LIFECYCLE_TEMPLATE_NOT_AVAILABLEUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
DYNAMIC_FIELDS_INVALIDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
DYNAMIC_FIELD_UNKNOWNUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
DYNAMIC_FIELD_REQUIREDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
DYNAMIC_FIELD_TYPE_INVALIDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
DYNAMIC_FIELD_OPTION_INVALIDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
CONTRACT_PDF_REQUIREDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
REQUIRED_FIELDS_MISSINGUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
CONTRACT_CORE_FIELDS_LOCKEDUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
WORKFLOW_FIELDS_REQUIRE_TRANSITIONUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
WORKFLOW_REQUIRED_FIELDS_MISSINGUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
WORKFLOW_REQUIRED_EVIDENCE_MISSINGUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
WORKFLOW_AI_REVIEW_PENDINGUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
WORKFLOW_FULFILLMENT_OPENUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
WORKFLOW_RECEIVABLES_OPENUso o status HTTP, message e details para mostrar o que corrigir; depois tente novamente.
WORKFLOW_NOTE_REQUIREDUso 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.