This guide summarizes the general response error categories as well as common errors specific to endpoints including Authentication, Business Management, Phone Numbers, and Program operations.
1. General Error Categories
400 - Validation Errors
Common Issues:
- Missing or Invalid Data: Required fields are missing or contain invalid data.
- Data Type Mismatch: Field values don't match the expected data type (e.g., passing a string when a number is expected).
- Value Out of Range: Field values exceed the allowed length or fall short of the minimum requirement.
- Pattern Mismatch: Data doesn't match the expected format (e.g., invalid email or phone number format).
- Field Conflicts: Values in certain fields conflict with other fields (e.g., duplicate values, improper relationships).
Action:
Check the request body for missing fields, formatting issues, or incorrect values. Ensure all data is in the correct type and meets required constraints.
403 - Authentication and Permission Errors
Common Issues:
- Insufficient Permissions: The provided key or token does not have the necessary permissions to perform the requested action.
- Access Denied: User is not authorized to access the resource or perform the operation.
Action:
Verify that the API key or token has the necessary permissions. Ensure that the user is authorized to access the resource or perform the action.
404 - Not Found Errors
Common Issues:
- Invalid ID: The provided resource ID (business, program, address, etc.) does not exist.
- Incorrect URL: Endpoint or resource does not exist at the specified path.
- Resource Missing: The requested resource (e.g., business address or program) cannot be found.
Action:
Double-check IDs in the URL and ensure they are correct. Ensure the resource exists in the correct environment (e.g., Production vs. Lab).
409 - Conflict Errors
Common Issues:
- Duplicate Entries: Attempting to create a resource that already exists (e.g., duplicate business name, program name).
- State Conflicts: A resource is in an invalid state for the requested operation (e.g., removing a grant from a business with active programs).
Action:
Ensure there are no conflicting resources or operations. Check if the resource already exists or if state conditions are met before performing the action.
500 and 503 Server Errors
Common Issues:
- Server Timeout: The server encountered a temporary issue and couldn’t process the request in time.
- Gateway Issues: Errors related to external services or network problems.
Action:
Retry the request. If the error persists, check if there are any known service interruptions or connectivity issues.
2. Specific Error Types Across Endpoints
Call Authentication (Push) Endpoint Errors
Common Issues:
Error Code 400:
- aNumber cannot be equal to bNumber – Cannot use call auth to authenticate a paired call between a phone number and itself.
- invalid character '[random_character]' looking for beginning of object key string – Check request body formatting.
- invalid request body – Check for typos, invalid fields, and formatting issues.
- object validation failed for field .[field]... – Check the mentioned field for typos or errors.
- phone number is missing additional vetting – Numbers in Sentry program require additional vetting.
- phone number is not approved – Numbers must be in an approved state to proceed.
- program is not enabled for call-pairing – Call authentication push is only needed for Paired programs.
- program schedule is expired – Extend the program or create a new one.
- Unable to validate the relationship between the phone number, program and/or business – Check if the phone number is listed under the correct business/program; verify key/token usage.
- unexpected EOF – Likely caused by a missing closing bracket in the request body.
Error Code 404:
- delivery channel not found – Program lacks the appropriate delivery channel(s).
- page not found – Check for errors in URI (/exchange/v1/calls/push).
- program not found – Verify programID and check if it belongs to the specified business.
Error Code 500:
- failed to get [PN/business/program] from exchange – Confirm the provided ID is valid, otherwise retry.
- One or more parameter values are not valid – Look for any invalid fields in the request body.
Error Code 504:
- precall request failed. please retry – Timeout error; retry later.
Create Business
Common Issues:
Error Code 400:
- administrative contact email invalid – Check email formatting.
- invalid character '}' looking for beginning of object key string – Check for extra commas or formatting errors.
- invalid request body – Contains invalid or unexpected fields.
- object validation failed for field [field]: value not in enum – Field doesn’t meet required values.
- object validation failed for field [field]: maximum exceeded – Value for the field is too long.
- object validation failed for field [field]: value does not match pattern – Ensure value matches the required format.
- object validation failed for field [field]: value is required – Missing a required field.
- object validation failed for field [field]: minimum exceeded – Value is too short.
- object validation failed for field [field]: wrong type passed – Field value type is incorrect.
- Vulgar Name, see Zendesk Ticket #1234 – Business name contains restricted word.
Error Code 409:
- duplicate [field] exists – Conflict due to another business having the same field value.
- resource state conflict – Possible duplicate requests sent in a short time span.
Error Code 503:
- unexpected HTTP status code received from server: 50X – Timeout; retry later.
Update Business
Common Issues:
Error Code 400:
- cannot update business context – Use the separate Update Business Context endpoint for such changes.
- invalid administrative contact – Use the separate Update Business Contact endpoint for changes.
- invalid business object – Field typo or invalid field case (e.g., taxId vs. taxID).
- invalid character 'xyz' looking for beginning of object key string – Check for bad formatting.
- invalid request body – Likely caused by incorrect formatting.
- object validation failed for field [field]: maximum exceeded – Truncate overly long values.
- object validation failed for field [field]: minimum exceeded – Ensure values meet minimum length.
- object validation failed for field [field]: wrong type passed – Check for field type mismatches.
Error Code 404:
- business not found – Check for typos in businessID, it might be in the Lab environment.
Error Code 409:
- duplicate legal_name exists – A business with the same legal name already exists.
- resource state conflict. please retry – Retry if there were multiple, short-duration requests.
Update Business Context
Common Issues
Error Code 400:
- cannot add a grant to a business if it is not present on the reseller – Ensure the reseller has grants before the business can inherit them.
- invalid character '[random_character]' looking for beginning of object key string – Review request body formatting.
- invalid request body – Review for invalid fields.
- invalid service grant – Ensure no typos and the service grants are valid.
- object validation failed for field .serviceGrants: value not in enum – Review serviceGrant formatting.
- programs missing shortName on delivery-channel – Ensure programs have valid shortName for specific carriers.
- this business's reseller does not have requested grants – Reseller must have required grants before they can be inherited by businesses.
Error Code 403:
- you are not permitted to receive entered service grants – The key/token used lacks the necessary permissions.
Error Code 404:
- business content not found – Ensure business has approved content before adding other carriers.
Error Code 409:
- business has a phone number already registered to a CE business – Use LOA for conflicting phone numbers.
Phone Number Errors
Common Issues:
Error Code 201:
- ALLOCATED_NUMBER_BUSINESS – Phone number exists under a different business within the same reseller.
- ALLOCATED_NUMBER_GRANT_CONFLICT – Phone number exists under another reseller.
- DUPLICATE_NUMBER – Duplicated phone number in the request.
- INVALID_NUMBER – Invalid phone number format.
- INVALID_RELATIONSHIP – Invalid BU-Program-Group-delivery channel relationship.
- RELATIONSHIP_NOT_FOUND – Invalid BU/Program not found.
Create Program
Common Issues:
Error Code 400:
- callerName channel vetting failed: Vulgar Name – Blocked due to vulgar word in the name.
- object validation failed for field [field]: value is required – Missing required field (e.g., longName, shortName).
- object validation failed for field [field]: minimum exceeded – Field value too short.
- object validation failed for field [field]: maximum exceeded – Field value too long.
- object validation failed for field [field]: value does not match pattern – Invalid characters or missing values.
- object validation failed for field [field]: value not in enum – Invalid value for the specified field.
- program name vetting failed: Government – Blocked due to government-related word.
Error Code 403:
- business does not have the correct service grants to allow this action – Ensure the business has the required service grants.
Error Code 404:
- business not found – Check for typos in businessID.
- business unit not found – Check for typos in businessUnitID.
Error Code 409:
- business content must be unique – Can't create identical content.
- program name already in use – Program name conflict.
Update Program
Common Issues
Error Code 400:
- object validation failed for field [field]: wrong type passed – Field value type mismatch.
Error Code 404:
- address not found – Check for typos in addressID or businessID.
- business not found – Ensure businessID is correct.
Error Code 409:
- resource state conflict. please retry – Retry if multiple requests are sent in a short time span.
3. Common Troubleshooting Actions
- Check Formatting: Ensure request bodies are correctly formatted (JSON or XML), and check for missing or extra commas, curly braces, or brackets.
- Verify IDs & Tokens: Double-check business, program, and phone number IDs, as well as any authentication tokens.
- Retry on 5XX Errors: Errors like 503 and 504 are often temporary and should resolve after retrying.
- Resolve Conflicts: Look for conflicts such as duplicate values, business unit mismatches, or invalid service grants.
