Zum Hauptinhalt springen

​
Überblick

Fehler werden in zwei Ebenen behandelt: zuerst der HTTP-Status, danach – falls vorhanden – error.code. Feldnamen und Code-Bezeichner bleiben unverändert, weil sie Teil des API-Vertrags sind.

​
Antwortformat

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

​
HTTP

StatusBedeutungEmpfehlung
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.Einsatz 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.Wiederholen idempotent reads with backoff.

​
Plan und Quota

CodeUmgang
PLAN_CONTRACT_LIMIT_EXCEEDEDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
PLAN_SEAT_LIMIT_EXCEEDEDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
PLAN_STORAGE_LIMIT_EXCEEDEDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
PLAN_FEATURE_NOT_ENABLEDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
PLAN_SUBSCRIPTION_REQUIREDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
PLAN_SUBSCRIPTION_INACTIVENutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
PLAN_NOT_AVAILABLENutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.

​
Datei und Upload

CodeUmgang
FILE_NAME_INVALIDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
FILE_SIZE_EMPTYNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
FILE_TOO_LARGENutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
FILE_CONTENT_TYPE_NOT_ALLOWEDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
FILE_EXTENSION_NOT_ALLOWEDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
FILE_KIND_NOT_ALLOWEDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
FILE_REF_INVALIDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
FILE_KIND_MISMATCHNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
FILE_SCAN_NOT_CLEANNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
FILE_SCAN_REQUEST_FAILEDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
FILE_BINDING_CONTEXT_MISMATCHNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
UPLOAD_OBJECT_KEY_MISMATCHNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
UPLOAD_OBJECT_NOT_FOUNDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
UPLOAD_OBJECT_SIZE_MISMATCHNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
UPLOAD_OBJECT_TYPE_MISMATCHNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
UPLOAD_OBJECT_CHECKSUM_MISMATCHNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
UPLOAD_TOKEN_INVALIDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
UPLOAD_TOKEN_EXPIREDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
UPLOAD_METADATA_MISMATCHNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.

​
Betrag und Rechnung

CodeUmgang
AMOUNT_REQUIREDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
AMOUNT_INVALIDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
AMOUNT_UNSAFE_NUMBERNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
AMOUNT_OUT_OF_RANGENutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
AMOUNT_SCALE_INVALIDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
UNSUPPORTED_CURRENCYNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
INVOICE_AMOUNT_EXCEEDS_TARGETNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.

​
Vertrag und Workflow

CodeUmgang
OWNER_SCOPE_RESTRICTEDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
ASSIGNEE_NOT_ACTIVE_TENANT_MEMBERNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
SUBJECT_NOT_FOUNDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
CONTRACT_TYPE_NOT_CONFIGUREDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
LIFECYCLE_STAGE_NOT_CONFIGUREDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
LIFECYCLE_TEMPLATE_NOT_AVAILABLENutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
DYNAMIC_FIELDS_INVALIDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
DYNAMIC_FIELD_UNKNOWNNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
DYNAMIC_FIELD_REQUIREDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
DYNAMIC_FIELD_TYPE_INVALIDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
DYNAMIC_FIELD_OPTION_INVALIDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
CONTRACT_PDF_REQUIREDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
REQUIRED_FIELDS_MISSINGNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
CONTRACT_CORE_FIELDS_LOCKEDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
WORKFLOW_FIELDS_REQUIRE_TRANSITIONNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
WORKFLOW_REQUIRED_FIELDS_MISSINGNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
WORKFLOW_REQUIRED_EVIDENCE_MISSINGNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
WORKFLOW_AI_REVIEW_PENDINGNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
WORKFLOW_FULFILLMENT_OPENNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
WORKFLOW_RECEIVABLES_OPENNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.
WORKFLOW_NOTE_REQUIREDNutzen Sie HTTP-Status, message und details, um die nötige Korrektur anzuzeigen; danach erneut versuchen.

​
Wiederholen

  • Idempotente GETs und 503-Lesezugriffe mit Backoff erneut versuchen.
  • Bei POST, PATCH und DELETE nach Timeout oder 5xx zuerst den aktuellen Ressourcenstatus prüfen.
  • 400, 401, 403, 404, 409 und 422 nicht unverändert erneut senden.