Voiso 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

Code	Text	When it happens
200	OK	The request completed successfully.
201	Created	A resource was created successfully.
400	Bad Request	The request is invalid, or input is missing or malformed. Returns `{ "error": "Bad Request" }`.
401	Unauthorized	The request is missing a valid API key. Returns `{ "error": "Unauthorized" }`.
403	Forbidden	The API key is valid, but does not have permission for the resource. Returns `{ "error": "Forbidden" }`.
404	Not found	The resource does not exist, or the endpoint path is invalid. Returns `{ "error": "Not found" }`.
406	Not Acceptable	The requested response format is not supported for the endpoint. Returns an `errors` object.
409	Conflict	The request conflicts with the current resource state. Returns an `errors` object.
422	Unprocessable Entity	One or more fields failed validation. Returns an `errors` object.
429	Too many requests	The request was rate limited. Returns `{ "error": "Too many requests" }`.

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)