> ## Documentation Index
> Fetch the complete documentation index at: https://docs.worthai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Error Handling - Send Business Invite

## Overview

This document provides comprehensive error handling guidance for external developers integrating with the Send Business Invite API endpoint. This endpoint creates a business invitation, optionally creating a new business or attaching the invite to an existing one, and sends an invitation email to the applicant. Each error scenario includes classification, sample responses, and actionable recommendations for handling the error in your application.

## Endpoint

```
POST /api/v1/customers/:customerID/businesses/invite
```

## Error Types

The endpoint can return errors classified into four main categories:

* **Validation Error**: Request format, schema, or data validation issues
* **Network Error**: HTTP method or connectivity issues
* **Authentication Error**: Authentication, authorization, or permission issues
* **Internal Server Error**: Server-side failures requiring retry logic

## Error Index

Quick navigation to specific error scenarios:

1. [Validation Error (Request Body Schema)](#1-validation-error-request-body-schema)
2. [Method Not Allowed Error](#2-method-not-allowed-error)
3. [Authentication Error (Missing or Invalid Token)](#3-authentication-error-missing-or-invalid-token)
4. [Authorization Error (Role Not Allowed)](#4-authorization-error-role-not-allowed)
5. [Data Permission Error](#5-data-permission-error)
6. [Insufficient Permissions Error](#6-insufficient-permissions-error)
7. [Onboarding Not Permitted For Customer](#7-onboarding-not-permitted-for-customer)
8. [Monthly Onboarding Limit Exhausted](#8-monthly-onboarding-limit-exhausted)
9. [Onboarding Template Version Errors](#9-onboarding-template-version-errors)
10. [Applicant Email Already Associated With An Account](#10-applicant-email-already-associated-with-an-account)
11. [Duplicate Business External ID](#11-duplicate-business-external-id)
12. [Existing Business Not Found](#12-existing-business-not-found)

***

## 1. Validation Error (Request Body Schema)

### Scenario

Request body does not match the required schema for sending a business invite.

### When It Happens

* Neither `applicants` nor `new_applicants` is provided (at least one is required)
* An applicant is missing `first_name`, `last_name`, or `email`
* `email` uses a disposable email domain, or isn't a valid email format
* `mobile` (applicant or business) isn't a valid phone number for the detected region
* Both `business`/`new_business` and `existing_business`/`existing_business_id` are provided together (these are mutually exclusive)
* Neither business information (`business`, `new_business`, `existing_business`, or `existing_business_id`) nor an existing business reference is provided
* `case_id` is provided without `existing_business_id` or `existing_business`
* Invalid UUID format for `customerID` in the URL path, or for any of `existing_business_id`, `case_id`, `esign_template_id`, `custom_field_template_id`, `template_version_id`, or `existing_applicant_ids`
* Extra fields that are not allowed are included in the request

### Classification

**Validation Error**

### Error Details

* **Error Class**: `ValidationMiddlewareError`
* **HTTP Status**: `400 Bad Request`
* **Error Code**: `INVALID`

### Sample API Response

```json theme={null}
{
  "status": "fail",
  "message": "Validation error message from schema",
  "errorCode": "INVALID",
  "data": {
    "errorName": "ValidationMiddlewareError"
  }
}
```

### Example Scenarios

* Missing applicants: `{ "new_business": { "name": "Acme Corp" } }`
* Invalid email: `{ "new_business": { "name": "Acme Corp" }, "new_applicants": [{ "first_name": "Jane", "last_name": "Doe", "email": "not-an-email" }] }`
* Conflicting business fields: `{ "business": { "name": "Acme Corp" }, "new_business": { "name": "Acme Corp" }, "new_applicants": [...] }`
* Invalid `customerID` UUID: `POST /api/v1/customers/invalid-uuid/businesses/invite`

### How to Handle

1. **Validate input before sending the request**: Confirm at least one applicant object is present and that business information is provided through exactly one of `business`, `new_business`, `existing_business`, or `existing_business_id`.
2. **Check field formats**: `email` must be a real, non-disposable address; `mobile` fields must be valid phone numbers for the applicable region.
3. **Do not retry automatically**: This is a client-side error that requires user action. Wait for the user to correct the input before retrying.

***

## 2. Method Not Allowed Error

### Scenario

Request uses an HTTP method other than POST (e.g., GET, PUT, DELETE, PATCH).

### When It Happens

* Client sends a non-POST request to `/customers/:customerID/businesses/invite`

### Classification

**Network Error** (HTTP method mismatch)

### Error Details

* **Error Class**: `MethodNotAllowedError`
* **HTTP Status**: `405 Method Not Allowed`
* **Error Code**: `NOT_ALLOWED`

### Sample API Response

```json theme={null}
{
  "status": "fail",
  "message": "Method Not Allowed",
  "errorCode": "NOT_ALLOWED",
  "data": {
    "errorName": "MethodNotAllowedError"
  }
}
```

### How to Handle

1. **Verify HTTP method**: Ensure you are using the `POST` method for this endpoint.
2. **Check your API client setup**: Review your HTTP client configuration (fetch, axios, etc.) to ensure the correct method is being used.
3. **No retry needed**: This is a permanent error that indicates incorrect API usage. Fix the HTTP method in your code and the request will succeed.

***

## 3. Authentication Error (Missing or Invalid Token)

### Scenario

Request is missing the Authorization header or the token is invalid, expired, or malformed.

### When It Happens

* Missing `Authorization` header
* Authorization header does not start with "Bearer"
* Token is expired, invalid, or malformed

### Classification

**Authentication Error**

### Error Details

* **Error Class**: `AuthenticationMiddlewareError`
* **HTTP Status**: `401 Unauthorized` or `400 Bad Request`
* **Error Code**: `UNAUTHENTICATED` or `INVALID`
* **Message**: Varies based on the specific error

### Sample API Response

**Missing Authorization Header:**

```json theme={null}
{
  "status": "fail",
  "message": "Authorization header not present",
  "errorCode": "UNAUTHENTICATED",
  "data": {
    "errorName": "AuthenticationMiddlewareError"
  }
}
```

**Invalid Authorization Header Format:**

```json theme={null}
{
  "status": "fail",
  "message": "Invalid Authorization header type",
  "errorCode": "INVALID",
  "data": {
    "errorName": "AuthenticationMiddlewareError"
  }
}
```

### How to Handle

1. **Check Authorization header**: Ensure your request includes a valid `Authorization` header in the format: `Authorization: Bearer <token>`.
2. **Handle token expiration**: Refresh the token and retry once with the new token. Do not retry automatically with the same token.
3. **Handle gracefully**: If authentication fails, redirect to your login flow or show an appropriate error message.

***

## 4. Authorization Error (Role Not Allowed)

### Scenario

The authenticated user does not have the required role (`CUSTOMER` or `ADMIN`) to access this endpoint.

### When It Happens

* User has the `APPLICANT` role (not allowed)
* User has a role that is not `CUSTOMER` or `ADMIN`

### Classification

**Authentication Error**

### Error Details

* **Error Class**: `RoleMiddlewareError`
* **HTTP Status**: `401 Unauthorized`
* **Error Code**: `UNAUTHORIZED`
* **Message**: `"Role Not Allowed"`

### Sample API Response

```json theme={null}
{
  "status": "fail",
  "message": "Role Not Allowed",
  "errorCode": "UNAUTHORIZED",
  "data": {
    "errorName": "RoleMiddlewareError"
  }
}
```

### How to Handle

1. **Verify user permissions**: This endpoint is only available to `CUSTOMER` and `ADMIN` role tokens.
2. **Do not retry**: This is a permanent authorization issue.
3. **Show appropriate message**: Display a message indicating the user does not have permission to perform this action.

***

## 5. Data Permission Error

### Scenario

A `CUSTOMER`-role user is attempting to send an invite for a `customerID` that does not belong to them.

### When It Happens

* The `customerID` in the URL path does not match the authenticated user's own customer

### Classification

**Authentication Error** (Data access restriction)

### Error Details

* **Error Class**: `AccessMiddlewareError`
* **HTTP Status**: `403 Forbidden`
* **Error Code**: `UNAUTHORIZED`
* **Message**: `"You are not allowed to access the data."`

### Sample API Response

```json theme={null}
{
  "status": "fail",
  "message": "You are not allowed to access the data.",
  "errorCode": "UNAUTHORIZED",
  "data": {
    "errorName": "AccessMiddlewareError"
  }
}
```

### How to Handle

1. **Verify customer ID**: Ensure the `customerID` in the URL path matches the authenticated user's own customer.
2. **Do not retry**: This is a permanent authorization issue.
3. **Fix the request**: If this is a bug in your integration, correct the `customerID` being sent.

***

## 6. Insufficient Permissions Error

### Scenario

A `CUSTOMER`-role user's assigned subrole does not grant the permissions required to send business invites.

### When It Happens

* Your organization has custom roles enabled, and the authenticated user's subrole does not include `businesses:write` or `businesses:create:invite`
* The authenticated user's token has no subrole assigned

<Note>
  This check only applies to `CUSTOMER`-role tokens with custom roles enabled for your organization. `ADMIN` tokens are never subject to this check, and it has no effect if custom roles aren't enabled for your account.
</Note>

### Classification

**Authentication Error** (Permission restriction)

### Error Details

* **Error Class**: `PermissionMiddlewareError`
* **HTTP Status**: `403 Forbidden`
* **Error Code**: `UNAUTHENTICATED`
* **Message**: `"User subrole not found"` or `"You do not have the necessary permissions to perform this action."`

### Sample API Response

```json theme={null}
{
  "status": "fail",
  "message": "You do not have the necessary permissions to perform this action.",
  "errorCode": "UNAUTHENTICATED",
  "data": {
    "errorName": "PermissionMiddlewareError"
  }
}
```

### How to Handle

1. **Verify subrole permissions**: Confirm the user's subrole has been granted `businesses:write` or `businesses:create:invite`.
2. **Do not retry**: This is a permanent authorization issue until the subrole's permissions are updated.
3. **Contact an admin**: Direct the user to an account administrator to adjust their subrole's permissions.

***

## 7. Onboarding Not Permitted For Customer

### Scenario

The customer account does not have permission to onboard businesses.

### When It Happens

* The customer's account is not provisioned with the `onboarding_module:write` permission

### Classification

**Authentication Error** (Account-level permission restriction)

### Error Details

* **Error Class**: `BusinessApiError`
* **HTTP Status**: `403 Forbidden`
* **Error Code**: `INVALID`
* **Message**: `"Customer does not have permission to onboard businesses."`

### Sample API Response

```json theme={null}
{
  "status": "fail",
  "message": "Customer does not have permission to onboard businesses.",
  "errorCode": "INVALID",
  "data": {
    "errorName": "BusinessApiError"
  }
}
```

### How to Handle

1. **Do not retry**: This is an account-provisioning issue, not something your request can fix.
2. **Contact support**: Reach out to your Worth Customer Success team to confirm your account is provisioned for onboarding.

***

## 8. Monthly Onboarding Limit Exhausted

### Scenario

The customer has reached their monthly onboarding limit and cannot send more invites.

### When It Happens

* The customer has already onboarded the maximum number of businesses allowed for the current month

<Note>
  This check is skipped for customers enrolled in the easy onboarding flow.
</Note>

### Classification

**Authentication Error** (Resource limit restriction)

### Error Details

* **Error Class**: `OnboardingLimitError`
* **HTTP Status**: `403 Forbidden`
* **Error Code**: `NOT_ALLOWED`
* **Message**: `"Monthly onboarding limit exhausted."`

### Sample API Response

```json theme={null}
{
  "status": "fail",
  "message": "Monthly onboarding limit exhausted.",
  "errorCode": "NOT_ALLOWED",
  "data": {
    "errorName": "OnboardingLimitError"
  }
}
```

### How to Handle

1. **Display the error message**: Show the error message clearly to the user.
2. **Do not retry**: This will persist until the next billing cycle or until the limit is increased.
3. **Contact support**: Provide a way for users to contact support if they need to increase their limit.

***

## 9. Onboarding Template Version Errors

### Scenario

The request includes `template_version_id`, but full onboarding configuration isn't enabled for the customer, or the referenced template version doesn't exist.

### When It Happens

* `template_version_id` is provided, but the customer doesn't have the full onboarding configuration setup enabled
* `template_version_id` is provided, but no matching template version exists for the customer

### Classification

**Validation Error** (Business logic validation)

### Error Details

**Full onboarding configuration not enabled:**

* **Error Class**: `BusinessApiError`
* **HTTP Status**: `400 Bad Request`
* **Error Code**: `INVALID`
* **Message**: `"Full onboarding configuration is not enabled for this customer"`

**Template version not found:**

* **Error Class**: `BusinessApiError`
* **HTTP Status**: `404 Not Found`
* **Error Code**: `NOT_FOUND`
* **Message**: `"Onboarding template version {template_version_id} not found for customer {customerID}"`

### Sample API Response

```json theme={null}
{
  "status": "fail",
  "message": "Onboarding template version 3fa85f64-5717-4562-b3fc-2c963f66afa6 not found for customer 3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "errorCode": "NOT_FOUND",
  "data": {
    "errorName": "BusinessApiError"
  }
}
```

### How to Handle

1. **Omit `template_version_id`** unless you intend to use a specific onboarding template version and full onboarding configuration is enabled for your account.
2. **Verify the template version ID**: Confirm it exists and belongs to the calling customer.
3. **Contact support**: If you believe full onboarding configuration should be enabled, contact your Worth Customer Success team.

***

## 10. Applicant Email Already Associated With An Account

### Scenario

An applicant's email address is already registered to a non-applicant account (for example, an existing customer or admin user).

### When It Happens

* An applicant in `applicants`/`new_applicants` has an `email` that already exists in the system under a role other than `APPLICANT`

### Classification

**Validation Error** (Business logic validation)

### Error Details

* **Error Class**: `BusinessApiError`
* **HTTP Status**: `400 Bad Request`
* **Error Code**: `INVALID`
* **Message**: `"Cannot onboard {email} to the platform. Contact support."`

### Sample API Response

```json theme={null}
{
  "status": "fail",
  "message": "Cannot onboard jane.doe@example.com to the platform. Contact support.",
  "errorCode": "INVALID",
  "data": {
    "errorName": "BusinessApiError"
  }
}
```

### How to Handle

1. **Verify the applicant's email**: Confirm the applicant is using an email address that isn't already tied to another Worth account.
2. **Do not retry with the same email**: This requires the user to provide a different email address, or to contact support.
3. **Display the error message**: Show the error to the user so they know which applicant needs a different email.

***

## 11. Duplicate Business External ID

### Scenario

The `external_id` provided on `business` or `new_business` already exists for this customer.

### When It Happens

* A business with the same `external_id` was already created for this customer (including soft-deleted businesses)
* A race condition causes the underlying database's uniqueness constraint to reject the insert

### Classification

**Validation Error** (Business logic validation)

### Error Details

* **Error Class**: `BusinessApiError`
* **HTTP Status**: `400 Bad Request`
* **Error Code**: `INVALID`
* **Message**: `"The business external ID already exists for this customer (business ID: {existing_business_id})"`, or, in rare race-condition cases, `"The business external ID already exists for this customer"` without an ID

### Sample API Response

```json theme={null}
{
  "status": "fail",
  "message": "The business external ID already exists for this customer (business ID: 9d75fc32-6770-4586-8dd6-9a9a0b6596b2)",
  "errorCode": "INVALID",
  "data": {
    "errorName": "BusinessApiError",
    "existing_business_id": "9d75fc32-6770-4586-8dd6-9a9a0b6596b2"
  }
}
```

### How to Handle

1. **Parse `data.existing_business_id`**: When present, use it to look up or reference the existing business instead of creating a duplicate.
2. **Use a unique `external_id`**: Generate or verify uniqueness of your external identifier before sending the request.
3. **Do not retry with the same `external_id`**: Correct the value first.

***

## 12. Existing Business Not Found

### Scenario

`existing_business_id` (or the `business_id` on `existing_business`) doesn't reference a business that this customer has onboarded.

### When It Happens

* The referenced business doesn't exist, is soft-deleted, or belongs to a different customer

<Note>
  Unlike the other business-logic errors on this page, this one does not set an explicit HTTP status or `errorCode`. It surfaces as a generic `500` response with `"status": "error"` and `"errorCode": "UNKNOWN_ERROR"` rather than a `"fail"`-style `4xx` response. Handle it by matching on the message text rather than the status code or error code.
</Note>

### Classification

**Validation Error** (Resource not found)

### Error Details

* **Error Class**: `BusinessApiError`
* **HTTP Status**: `500 Internal Server Error`
* **Error Code**: `UNKNOWN_ERROR`
* **Message**: `"This business was not onboarded by the current customer."`

### Sample API Response

```json theme={null}
{
  "status": "error",
  "message": "This business was not onboarded by the current customer.",
  "errorCode": "UNKNOWN_ERROR",
  "data": null
}
```

### How to Handle

1. **Verify the business reference**: Confirm `existing_business_id` (or `existing_business.business_id`) is correct and belongs to the calling customer.
2. **Match on message text**: Because this error doesn't use a distinguishing status code or error code, detect it by checking the `message` field rather than treating every `500` as a transient server error.
3. **Do not blindly retry**: Retrying without correcting the business reference will fail the same way every time.

***

## Related Documentation

* [API Reference: Send Business Invite](/api-reference/case/invites/send-business-invite) - Complete endpoint and schema documentation
* [Overview](/onboarding-sdk-3/overview) - Return to the SDK 3 overview

***

## Support

For questions or issues, please contact your Worth Customer Success team or reach out to [support@joinworth.com](mailto:support@joinworth.com).