Saltar al contenido principal

​
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

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

​
HTTP

EstadoSignificadoAcción 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.Reintento idempotent reads with backoff.

​
Plan y cuota

CódigoManejo
PLAN_CONTRACT_LIMIT_EXCEEDEDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
PLAN_SEAT_LIMIT_EXCEEDEDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
PLAN_STORAGE_LIMIT_EXCEEDEDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
PLAN_FEATURE_NOT_ENABLEDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
PLAN_SUBSCRIPTION_REQUIREDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
PLAN_SUBSCRIPTION_INACTIVEUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
PLAN_NOT_AVAILABLEUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.

​
Archivo y subida

CódigoManejo
FILE_NAME_INVALIDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
FILE_SIZE_EMPTYUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
FILE_TOO_LARGEUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
FILE_CONTENT_TYPE_NOT_ALLOWEDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
FILE_EXTENSION_NOT_ALLOWEDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
FILE_KIND_NOT_ALLOWEDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
FILE_REF_INVALIDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
FILE_KIND_MISMATCHUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
FILE_SCAN_NOT_CLEANUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
FILE_SCAN_REQUEST_FAILEDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
FILE_BINDING_CONTEXT_MISMATCHUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
UPLOAD_OBJECT_KEY_MISMATCHUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
UPLOAD_OBJECT_NOT_FOUNDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
UPLOAD_OBJECT_SIZE_MISMATCHUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
UPLOAD_OBJECT_TYPE_MISMATCHUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
UPLOAD_OBJECT_CHECKSUM_MISMATCHUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
UPLOAD_TOKEN_INVALIDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
UPLOAD_TOKEN_EXPIREDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
UPLOAD_METADATA_MISMATCHUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.

​
Importe y factura

CódigoManejo
AMOUNT_REQUIREDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
AMOUNT_INVALIDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
AMOUNT_UNSAFE_NUMBERUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
AMOUNT_OUT_OF_RANGEUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
AMOUNT_SCALE_INVALIDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
UNSUPPORTED_CURRENCYUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
INVOICE_AMOUNT_EXCEEDS_TARGETUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.

​
Contrato y workflow

CódigoManejo
OWNER_SCOPE_RESTRICTEDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
ASSIGNEE_NOT_ACTIVE_TENANT_MEMBERUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
SUBJECT_NOT_FOUNDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
CONTRACT_TYPE_NOT_CONFIGUREDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
LIFECYCLE_STAGE_NOT_CONFIGUREDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
LIFECYCLE_TEMPLATE_NOT_AVAILABLEUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
DYNAMIC_FIELDS_INVALIDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
DYNAMIC_FIELD_UNKNOWNUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
DYNAMIC_FIELD_REQUIREDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
DYNAMIC_FIELD_TYPE_INVALIDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
DYNAMIC_FIELD_OPTION_INVALIDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
CONTRACT_PDF_REQUIREDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
REQUIRED_FIELDS_MISSINGUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
CONTRACT_CORE_FIELDS_LOCKEDUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
WORKFLOW_FIELDS_REQUIRE_TRANSITIONUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
WORKFLOW_REQUIRED_FIELDS_MISSINGUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
WORKFLOW_REQUIRED_EVIDENCE_MISSINGUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
WORKFLOW_AI_REVIEW_PENDINGUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
WORKFLOW_FULFILLMENT_OPENUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
WORKFLOW_RECEIVABLES_OPENUsa el estado HTTP, message y details para mostrar qué corregir; luego reintenta.
WORKFLOW_NOTE_REQUIREDUsa 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.