Error responses

Unsuccessful requests are answered with an HTTP status code in the 400 or 500 range and, in most cases, a JSON body that describes the error:

{
    "error": "InvalidRecord",
    "explanation": "Record Validation errors",
    "details": {
        "name": "Required",
        "fieldset_login.login": "Such login already exists"
    }
}

Attribute	Description
error	Error code. Use it to distinguish error types in your application.
explanation	Short human-readable explanation of the error.
details	Additional details, or null. For validation errors, a dictionary that maps attribute names to messages. Nested attributes use dot notation, for example fieldset_login.login.

Status codes and error codes

Status	error	When it is returned
400 Bad Request	InvalidRecord	The submitted object fails validation. details lists the invalid attributes.
400 Bad Request	InvalidJsonFormat	The request body is not valid JSON, or the top-level key (for example "user") is missing.
400 Bad Request	InvalidParameter	A query parameter is missing or invalid, for example action for pause and resume recording, or expires for a signed URL.
400 Bad Request	InvalidGeneral, Bad Request	The request cannot be completed for another reason, for example a daterange in a wrong format. explanation or details describes it.
401 Unauthorized	Unauthorized	Credentials are missing or not valid, the user has no REST API permission, or the user authenticates through LDAP or single sign-on. The response has a WWW-Authenticate header.
403 Forbidden	Forbidden, PermissionError	The user is authenticated, but the role has no permission for this operation or this record.
404 Not Found	NotFound	No resource with such ID exists, the ID is not a valid UUID, the URL is wrong, or the resource is outside the access scope of the API user.
409 Conflict	InvalidState, NotEmptyError, Conflict	The request conflicts with the current state of the resource. For example, deleting a tenant, group, or role that still has users, or pausing recording of a call that is not active.
429 Too Many Requests	Too Many Requests	The tenant's request rate limit is exceeded, or too many sign-in attempts failed. See Rate limits.
500 Internal Server Error	InternalError, DatabaseError	Unexpected failure on the server. Contact the system administrator with the details value.

Examples

Authentication failure:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="miarec"
Content-Type: application/json

{"error": "Unauthorized", "explanation": "Credentials are not valid", "details": null}

Missing permission:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{"error": "Forbidden", "explanation": "Not sufficient permissions", "details": null}

Unknown resource:

HTTP/1.1 404 Not Found
Content-Type: application/json

{"error": "NotFound", "explanation": "Resource not found or URL is not valid", "details": "/api/v2/calls/00000000-0000-0000-0000-000000000000.json"}

Deleting a group that still has users:

HTTP/1.1 409 Conflict
Content-Type: application/json

{"error": "NotEmptyError", "explanation": "Other resources refer to this one", "details": "Cannot delete a group, which has users"}

Note

A 404 Not Found does not always mean that the record does not exist. Records that the API user is not allowed to see are reported as not found, so that the API does not reveal their existence.