This page documents all standard errors that may occur across the API. Note that method-specific documentation pages typically show only the most relevant errors for that particular endpoint. Common errors like BAD_REQUEST for malformed JSON or UNKNOWN_VERSION for a bad version header may not be explicitly listed on every method page, but could still occur. Always refer to this comprehensive list when troubleshooting any error response.

Authentication errors are documented separately in the Authentication Errors page for better organization.

ACCOUNT_CONFIGURATION_VIOLATION

This error occurs when a request violates account-specific configuration rules for the account. These configurations can be adjusted by account administrators. For information about available configuration options or to request changes, please contact [email protected]. The HTTP status code returned is 400.

In addition to the standard code and message fields, this error includes entity_type and sub_code fields to provide more specific information about the configuration violation. See Account Configuration Violations for a complete list of entity types and sub-codes.

Example

{
  "errors": [
    {
      "code": "ACCOUNT_CONFIGURATION_VIOLATION",
      "sub_code": "MINIMUM_OWNERSHIP_PERCENTAGE",
      "entity_type": "BusinessOwner",
      "message": "Owner must have at least 25% ownership to be added as a beneficial owner."
    }
  ]
}

BAD_REQUEST

This error occurs when the request is malformed, missing a required value, the value supplied is not appropriate for the type, or other related request-based problems. The HTTP status code returned is 400.

Examples

{
  "errors": [
    {
      "code": "BAD_REQUEST",
      "message": "The request body is malformed JSON."
    }
  ]
}

{
  "errors": [
    {
      "code": "BAD_REQUEST",
      "message": "Invalid request params.",
      "details": [
        {
          "field": "business.tax_id",
          "message": "tax_id is required."
        },
        {
          "field": "business.phone_number",
          "message": "phone_number must be only digits [0-9]."
        }
      ]
    }
  ]
}

ENTITY_LINKED

This error occurs when an attempt is made to delete an entity that is linked to other entities. For example, trying to delete a Person that is linked to a Business as an owner, or trying to delete a Bank Account that is linked to a Business. The HTTP status code returned is 400.

Example

{
  "errors": [
    {
      "code": "ENTITY_LINKED",
      "message": "The Person cannot be deleted because it is linked to one or more Business entities as an owner."
    }
  ]
}

ENTITY_NOT_FOUND

This error occurs when request references an entity that does not exit. For example, providing an account_id that does not correspond to an existing account. The HTTP status code returned is 400.

Example

{
  "errors": [
    {
      "code": "ENTITY_NOT_FOUND",
      "message": "The given entity(s) does not exist.",
      "details": [
        {
          "account_id": "sb_j8gh53b"
        }
      ]
    }
  ]
}

GATEWAY_TIMEOUT

This error occurs when the infrastructure experiences connectivity issues, resulting in a timeout. The HTTP status code returned is 504.

Example

{
  "errors": [
    {
      "code": "GATEWAY_TIMEOUT",
      "message": "The request timed out while waiting for a response from the server."
    }
  ]
}

INTERNAL_SERVER_ERROR

This error is used for most server error cases when no other specific 500-level status code applies. The HTTP status code returned is 500.

Example

{
  "errors": [
    {
      "code": "INTERNAL_SERVER_ERROR",
      "message": "An unexpected error occurred while processing your request."
    }
  ]
}

INVALID_ENDPOINT_REQUEST

This error occurs when API Gateway cannot process the request due to: an invalid endpoint path, an unsupported HTTP method for the endpoint, malformed JSON in the request body, or security policy violations (such as geographic restrictions). The HTTP status code returned is 400.

Example

{
  "errors": [
    {
      "code": "INVALID_ENDPOINT_REQUEST",
      "message": "The request could not be processed. This may occur if: the endpoint does not exist, the HTTP method is not supported (verify you're using POST), the request body contains invalid JSON, or the request was blocked by security policy (e.g. geographic restrictions). Refer to the API documentation for valid endpoints and methods."
    }
  ]
}

MISSING_REQUIREMENTS

This error occurs when there are missing requirements to perform an specific action, such as workflow.complete or workflow.pricing.calculate. The HTTP status code returned is 400.

Example

{
  "errors": [
    {
      "code": "MISSING_REQUIREMENTS",
      "details": [
        {
          "code": "STARETD_WORKFLOW_REQUIRED",
          "entity_type": "Workflow",
          "message": "Workflow with `STARTED` state is required.",
          "related_methods": [
            "workflow.start"
          ]
        },
        {
          "code": "CONTROL_PRONG_REQUIRED",
          "entity_type": "BusinessOwner",
          "message": "Business owner with `CONTROL_PRONG` ownership type is required.",
          "related_methods": [
            "person.create",
            "business.addOwner"
          ]
        },
        {
          "code": "FIELDS_REQUIRED",
          "entity_type": "BusinessOwner",
          "entity_id": "bo_5nCWRq51h3ILIJvOOhfF4i",
          "message": "Business owner `bo_5nCWRq51h3ILIJvOOhfF4i` is missing fields",
          "related_methods": [
            "businessOwner.update"
          ],
          "fields": [
            "last_name",
            "date_of_birth",
            "title",
            "citizenship",
            "phone_number",
            "address.line1",
          ]
        },
        {
          "code": "PRIMARY_BANK_ACCOUNT_REQUIRED",
          "entity_type": "BusinessBankAccount",
          "message": "Business bank account with `PRIMARY` purpose is required.",
          "related_methods": [
            "bankAccount.create",
            "business.addBankAccount"
          ]
        },
        {
          "code": "FIELDS_REQUIRED",
          "entity": "BankAccount",
          "entity_id": "ba_6zNzQZHSf26V83BO3uW6dS",
          "message": "Bank account `ba_6zNzQZHSf26V83BO3uW6dS` is missing fields",
          "related_endpoints": [
            "bankAccount.update"
          ],
          "fields": [
            "bank_routing_number",
            "bank_account_type"
          ]
        },
        {
          "code": "FIELDS_REQUIRED",
          "entity": "BusinessBankAccount",
          "entity_id": "bba_79HaMs4zgYfilF3xQuJy3J",
          "message": "Business bank account `bba_79HaMs4zgYfilF3xQuJy3J` is missing fields",
          "related_endpoints": [
            "business.updateBankAccount"
          ],
          "fields": [
            "bank_account_purposes"
          ]
        },
        {
        "code": "CALCULATED_PRICING_REQUIRED",
        "entity": "Workflow",
        "entity_id": "w_7h1EpxerrZQyLnRC1EQ9Ck",
        "message": "Pricing for workflow `w_7h1EpxerrZQyLnRC1EQ9Ck` has not been calculated.",
        "related_endpoints": [
          "workflow.pricing.calculate"
        ],
      }
      ]
    }
  ]
}

PAYLOAD_TOO_LARGE

This error occurs when the request is too large. The HTTP status code returned is 413. Because payload size is enforced by our infrastructure, trace_idwill not be included in meta field of the response.

There are two different scenarios where this error might occur:

If the request exceeds 10 MB (10,485,760 bytes), you will receive a plain text response with a Content-Type of "text" and a body containing only: HTTP content length exceeded 10485760 bytes. This limitation is enforced by our infrastructure and cannot be customized.
For requests under 10 MB but exceeding our internal size limits, you will receive a JSON error response:

Example

{
  "errors": [
    {
      "code": "PAYLOAD_TOO_LARGE",
      "message": "The request payload exceeds the maximum allowed size."
    }
  ]
}

SERVICE_UNAVAILABLE

This error is used when the service is offline, such as during maintenance. The HTTP status code returned is 503.

Example

{
  "errors": [
    {
      "code": "SERVICE_UNAVAILABLE",
      "message": "The service is currently unavailable. Please try again later."
    }
  ]
}

SYSTEM_RULE_VIOLATION

This error occurs when a request violates one of the core system rules that cannot be modified. These rules define fundamental constraints and relationships within the platform. The HTTP status code returned is 400.

In addition to the standard code and message fields, this error includes entity_type and sub_code fields to provide more specific information about the rule violation. See System Rule Violations for a complete list of entity types and sub-codes.

Example

{
  "errors": [
    {
      "code": "SYSTEM_RULE_VIOLATION",
      "sub_code": "INVALID_SUBJECT_RECORD_TYPE",
      "entity_type": "Workflow",
      "message": "A Business Application workflow requires a Business-type Subject Record.",
    }
  ]
}

SYSTEM_EXCEPTION

This error occurs when a request can't be completed because the conditions for it are not met. The HTTP status code returned is 400.

In addition to the standard code and message fields, this error includes entity_type and sub_code fields to provide more specific information about the error. See System Exceptions for a complete list of entity types and sub-codes.

Example

{
  "errors": [
    {
      "code": "SYSTEM_EXCEPTION",
      "sub_code": "DEFENSE_DOCUMENT_IN_PROGRESS",
      "entity_type": "Workflow",
      "message": "Defense Document is still being generated and is not ready for download",
    }
  ]
}

THROTTLED

This error occurs when the API request rate exceeds the defined limits. The HTTP status code returned is 429.

Example

{
  "errors": [
    {
      "code": "THROTTLED",
      "message": "Request rate limit exceeded. Please slow down your request rate."
    }
  ]
}

UNAUTHORIZED

This error is returned when authentication succeeds, but the entity is not allowed to perform the function or doesn't have access to the underlying resource(s). The HTTP status code returned is 403.

Example

{
  "errors": [
    {
      "code": "UNAUTHORIZED",
      "message": "The API Key 'sb_3eY9UJuj09636NVPlgmhfa' is not authorized for this request."
    }
  ]
}

UNKNOWN_VERSION

This error occurs when the X-API-Version header value does not correspond with a known version. The HTTP status code returned is 400. Because version enforcement is handled by our infrastructure, trace_idwill not be included in meta field of the response.

Example

{
  "errors": [
    {
      "code": "UNKNOWN_VERSION",
      "message": "Unknown API version specified. Please use a valid version. The current version is '2025-03-24'."
    }
  ]
}

UNSUPPORTED_MEDIA_TYPE

This error occurs when the media type of the request is not supported. Most APIs accept application/json, and this error is returned if any other media type is sent. The HTTP status code returned is 415.

Example

{
  "errors": [
    {
      "code": "UNSUPPORTED_MEDIA_TYPE",
      "message": "The media type provided is not supported. Please check the Content-Type header. Most of our API endpoints accept 'application/json'."
    }
  ]
}