Skip to main content

​
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)
  2. Method Not Allowed Error
  3. Authentication Error (Missing or Invalid Token)
  4. Authorization Error (Role Not Allowed)
  5. Data Permission Error
  6. Insufficient Permissions Error
  7. Onboarding Not Permitted For Customer
  8. Monthly Onboarding Limit Exhausted
  9. Onboarding Template Version Errors
  10. Applicant Email Already Associated With An Account
  11. Duplicate Business External ID
  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

{
  "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

{
  "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: 
{
  "status": "fail",
  "message": "Authorization header not present",
  "errorCode": "UNAUTHENTICATED",
  "data": {
    "errorName": "AuthenticationMiddlewareError"
  }
}
Invalid Authorization Header Format: 
{
  "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

{
  "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

{
  "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
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.

​
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

{
  "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

{
  "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
This check is skipped for customers enrolled in the easy onboarding flow.

​
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

{
  "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

{
  "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

{
  "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

{
  "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
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.

​
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

{
  "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.

​
Support

For questions or issues, please contact your Worth Customer Success team or reach out to support@joinworth.com.