If a request fails, the Priority Commerce Engine (PCE) rejects the whole request and doesn't create the business. The response lists each problem in errors, one entry per field. Fix those fields and send the request again.

Read an error response

A failed request returns the problem in this shape. The HTTP status names the kind of failure, and errors lists each field to fix.

{
  "traceId": "5c2e8f14-7a3b-4d91-b6c5-9e1f3a7d2b48",
  "timestamp": "2026-09-15T14:32:08.214Z",
  "errorCode": "REQUEST_VALIDATION_FAILED",
  "message": "Validation failed",
  "errors": [
    {
      "field": "legalName",
      "code": "REQUIRED",
      "message": "legalName is required"
    },
    {
      "field": "owners[0].ownershipPercentage",
      "code": "OUT_OF_RANGE",
      "message": "ownershipPercentage must be between 0 and 100"
    }
  ]
}

Field	What it tells you
`traceId`	The ID of this request. Give it to Priority support if you need help.
`timestamp`	When the error happened (ISO 8601, UTC).
`errorCode`	The kind of problem. See the table below.
`errors[].field`	Where the problem is. For example, `owners[0].ownershipPercentage` means the `ownershipPercentage` of the first owner.
`errors[].code`	A short code for the field problem, such as `REQUIRED` or `INVALID_ENUM_VALUE`.
`errors[].message`	What's wrong, in words.

Each errorCode tells you the kind of problem:

`errorCode`	What it means
`REQUEST_VALIDATION_FAILED`, `VALIDATION_FAILED`	A required value is missing or not allowed.
`UNPROCESSABLE_INPUT`	A value is there but is too long, too short or badly formatted.
`NOT_FOUND`	The ID in the path doesn't exist.
`DUPLICATE_EXTERNAL_ID`	You already used this `externalId` on another record. Send a different value to create a new one.
`RESOURCE_CONFLICT`	A value that must be unique, such as an SSN or government ID, is already linked to another person. Link the person who already exists instead of adding them again.

Some checks can't run at submit time. Priority also verifies who the business is and who owns it (KYB, or Know Your Business). A KYB problem can surface after a successful create. It appears on the service's errors list, with a level and a fieldPath:

{
  "fieldPath": "owners[].isControlPerson or signatories[].isControlPerson",
  "level": "mandatory",
  "message": "Exactly one owner or signatory must be marked as the Control Person."
}

To read and resolve a problem that surfaces after create, see Underwriting exceptions.

Common messages

These messages appear exactly as the API returns them. Search this page for the text you received.

The business

Message	What went wrong
`legalName is required`	The legal name is missing.
`legalName must be shorter than or equal to 255 characters`	The legal name is longer than 255 characters.
`businessDescription must be shorter than or equal to 512 characters`	The description is longer than 512 characters.
`email must be an email`	The email address isn't valid.
`externalId must be shorter than or equal to 255 characters`	Your `externalId` is longer than 255 characters.
`taxIds.0.value must be a valid 9-digit ITIN beginning with 9 (e.g. 9XX-XX-XXXX)`	The ITIN (a US tax number for people without an SSN) isn't 9 digits starting with 9.
`Tax ID type must be EIN for corporations, S-corporations, LLCs, LLPs and partnerships.`	This kind of business must use an EIN (the US tax number for a company).

Which tax ID each kind of business needs is on Business validation and KYB rules.

Owners and signatories

Owners are the people who own part of the business. Signatories can sign for it. The control person is the one person who runs the business day to day, such as the CEO. In these messages, "signatory" means every person Priority must identify.

Message	What went wrong
`Exactly one owner or signatory must be marked as the Control Person.`	Nobody is marked as the person who runs the business.
`Beneficial-owner ownership must be 0 for government, non-profit and 501(c)(3) tax exempt.`	A non-profit or government business lists owners with a share above 0%.
`Total beneficial-owner ownership must be at least 50% for partnerships.`	A partnership's owners add up to less than 50%.
`Every signatory (control person, owner and guarantor) requires a primary identification (SSN) for acquiring.`	A person has no SSN or ITIN.
`Every signatory (control person, owner and guarantor) requires a secondary identification (government id) for acquiring.`	A person has no government ID, such as a driver license.
`SSN or Government ID is already associated with another owner.`	An SSN or government ID is already linked to another owner (returns `409`).
`Duplicate signatory detected. The same SSN or government ID cannot be used for more than one signatory.`	The same SSN or government ID is used for two signatories (returns `409`).
`ownershipPercentage must be a non-negative amount with at most 2 decimal places`	An ownership share has more than 2 decimal places.

Locations and addresses

A location is a place where the business sells. Accept Payments needs details about how it takes cards at each location.

Message	What went wrong
`An industry MCC code is required for acquiring.`	The MCC (the code for what the business sells) is missing.
`An industry category or description is required for acquiring.`	The industry category or description is missing.
`MOTO, eCommerce and card-present percentages are required and must total 100% for acquiring.`	The card mix (how card payments split between phone or mail orders, online and in person) doesn't add up to 100%.
`addresses.0.type must be one of the following: registered, mailing, physical, headquarters, home, work`	The address type isn't one of the allowed values.
`addresses.0.postalCode must be a valid postal code`	The postal code isn't valid.

Bank accounts

Message	What went wrong
`bankAccounts.0.routingNumber must be a valid 9-digit routing number`	The routing number isn't 9 digits.
`accountType must be one of: checking, savings`	The account type isn't checking or savings.
`Duplicate externalId '…' provided for multiple bank accounts in the same request`	Two bank accounts in one request have the same `externalId`.

The request itself

Status	Message	What went wrong
`400`	`Body is not valid JSON but content-type is set to 'application/json'`	The body isn't valid JSON.
`400`	`Body cannot be empty when content-type is set to 'application/json'`	The body is empty.
`401`	`Unauthorized`	The API key is missing or not valid.
`404`	`business with ID "…" not found`	No business has that ID.
`409`	`externalId "…" is already in use` / `SSN or Government ID is already associated with another owner.`	A value that must be unique is already in use: an `externalId`, or an SSN or government ID linked to another person.
`422`	`property … should not exist`	You sent a query parameter PCE doesn't know.
`422`	`limit must be an integer between 1 and 250`	`limit` is outside 1 to 250.

If you send a record back exactly as you read it, PCE rejects it. A read includes fields only PCE sets, such as masked numbers. Send only the fields you're changing.

For what each status code means, see HTTP response codes.

Next steps

Underwriting exceptions

Fix what underwriting flags on a service.

Business validation and KYB rules

See the rules behind these messages.