Errors

Clients must be prepared to handle a variety of error that may be returned by the server. Error responses will have an appropriate HTTP status code and the response body will contain a JSON representation of the error:

Name Type Description Example
id string Unique string identifying error type “access_denied”
code integer Unique number identifying error type 102
message string Human-readable error details “The participants list cannot be omitted”
url string A URL to the docs with more information
data object A free-form object of additional data specific to the error { “nonce”: “38ca1bb2-2560-5989ce9b2b66” }

Errors specific to an endpoint are documented with each endpoint above. In addition, there are some errors that may occur with any endpoint:

ID Code HTTP Status Description
service_unavailable 1 503 (Service Unavailable) The operation could not be completed because a backend service could not be accessed
invalid_request_id 3 400 (Bad Request) The client has supplied a request ID that is not a valid UUID
authentication_required 4 401 (Unauthorized) The action could not be completed because the client is unauthenticated The response will include a nonce for satisfying an authentication challenge
app_suspended 5 403 (Forbidden) The client has supplied an app ID that has been suspended
user_suspended 6 403 (Forbidden) The client has supplied a user ID that has been suspended
rate_limit_exceeded 7 429 (Too Many Requests) The client has sent too many requests in a given amount of time
request_timeout 8 408 (Request Timeout) or None The server or the client timed out waiting for a request to complete
invalid_operation 9 422 (Unprocessable Entity) or None The server or client has declined to perform an invalid operation (i.e. deleting an unsent message)
invalid_request 10 400 (Bad Request) The request is structurally invalid
internal_server_error 100 500 (Internal Server Error) The operation could not be completed because an unexpected error occurred
access_denied 101 403 (Forbidden) The authenticated user does not have access to the resource requested
not_found 102 404 (Not Found) The resource requested could not be found
object_deleted 103 410 (Gone) The resource requested has been deleted
missing_property 104 422 (Unprocessable Entity) A property with a required value was not supplied
invalid_property 105 422 (Unprocessable Entity) A property was supplied with an invalid value
invalid_endpoint 106 404 (Not Found) The client has referenced an endpoint that does not exist
invalid_header 107 406 (Not Acceptable) Invalid Accept header; must be of form application/vnd.layer+json; version=x.y
conflict 108 409 (Conflict) The distinct conversation already exists with conflicting metadata
method_not_allowed 109 405 (Method Not Allowed) The HTTP method used is not allowed for the given resource
version_mismatch 110 501 (Not Implemented) The requested endpoint is only available in a different version of the API
id_in_use 111 409 (Conflict) The specified ID is already in use
permission_denied 113 403 (Forbidden) The client does not have permission to perform the requested operation
participant_blocked 116 422 (Unprocessable Entity) The conversation could not be created because at least one participant is blocked
invalid_id 203 400 (Bad Request) The client has supplied an ID that is not a valid UUID

service_unavailable

There are issues on the server; typically these resolve in a few minutes, and you can retry your request soon. If the issue does not clear, contact support@layer.com.

invalid_request_id

The client has supplied a request ID that is not a valid UUID. You can try and validate your UUID with a public UUID validator such as this one.

access_denied

You have attempted to access a resource to which your user does not have permissions. Typically this means that the user was a participant of this Conversation, but is no longer a participant. So it still shows up in their data, but they no longer have permissions to operate upon it.

permission_denied

You have attempted to perform an operation that requires a specific permission that you do not have. The required permission will be denoted in the permission_required property in the data supplied with the error.

not_found

You have attempted to access a resource that was not found. Typical causes include:

  1. The resource was deleted
  2. The resource ID is incorrect
  3. The user has never been a participant who can access this data; from the user’s perspective, this data does not exist.

invalid_header

This error typically occurs when:

  1. A request is made without an appropriate Accept header; see API Versioning for header requirements.
  2. A request was made with an appropriate Accept header, but requested a version that is not available.
  3. A PATCH operation is performed with an incorrect Content-Type header; see Layer-Patch for header requirements.