Error codes

API uses standard HTTP response codes to indicate whether a request succeeded or failed.

• 2xx codes indicate a successful request.
• 4xx codes indicate a request error, for example missing parameters, invalid values, missing authentication, or missing permissions.
• 5xx codes indicate an unexpected server error.

Tip: Check each endpoint page for the specific response codes that endpoint can return.

Error response format

Simple errors

Some errors return a JSON object with an error string.

{
  "error": "Unauthorized"
}

Common values include:

• Bad Request
• Unauthorized
• Forbidden
• Not found
• Too many requests

Validation and conflict errors

Some errors return a JSON object with an errors object. The keys are field names or parameter names and the values are arrays of messages.

This format is used for 422 Unprocessable Entity, and can also be used for 406 Not Acceptable and 409 Conflict.

{
  "errors": {
    "parameter1": ["is missing"],
    "parameter2": ["must be a string"]
  }
}

Response codes used in v4

How to troubleshoot

1) You get 401 Unauthorized

Most common causes:

• Missing Authorization header
• Using the wrong token format, it must be a Bearer token
• Using a key from a different environment or contact center

Example (missing Authorization header):

curl -X GET "https://{cluster_id}.voiso.com/api/v4/users" \
  -H "Content-Type: application/json"

Fix:

curl -X GET "https://{cluster_id}.voiso.com/api/v4/users" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json"

2) You get 422 Unprocessable Entity

This means the request is valid JSON, but one or more fields failed validation. The response includes details per field.

Example response:

{
  "errors": {
    "name": ["is missing"],
    "timezone": ["must be a string"]
  }
}

What to check:

• Required fields are present
• Field types match the schema (string vs number vs boolean)
• Enum values match exactly, including case

3) You get 403 Forbidden

This means the key is valid, but it cannot access what you requested.

What to check:

• The key belongs to the correct contact center
• Your role permissions allow access to that resource and action

Typical response:

{
  "error": "Forbidden"
}

4) You get 404 Not found

Most common causes:

• Wrong path, wrong API version, or typo in the URL
• Resource ID does not exist

Typical response:

{
  "error": "Not found"
}

What to check:

• Base URL is correct: https://{cluster_id}.voiso.com
• You are calling /api/v4/... (not /api/v1/...)
• The identifier you passed is correct

5) You get 406 Not Acceptable

This means the endpoint cannot return the response format you requested.

What to check:

• Your Accept header is valid for the endpoint.
• Try Accept: application/json if you are unsure which formats are supported.

Typical response format:

{
  "errors": {
    "format": ["must be one of: json, vtt, srt, text"]
  }
}

6) You get 409 Conflict

This means the request conflicts with the current state of the resource.

Common cases include:

• You tried to change a resource that is in a state that does not allow the requested operation.
• You requested a feature output that is not available yet.

Typical response format:

{
  "errors": {
    "state": ["conflict"]
  }
}

What to do:

• Check the resource status using the relevant GET endpoint.
• Retry only after the resource status changes, or after the requested output becomes available.

7) You get 429 Too many requests

This means your client is being rate limited.

Typical response:

{
  "error": "Too many requests"
}

What to do:

• Reduce request frequency
• Retry with backoff (wait a short time before retrying, increase the wait on repeated 429s)