Errors

A failed request returns an HTTP error status and an error object:

{
  "error": {
    "code": "PROJECT_NOT_FOUND_EXCEPTION",
    "message": "Project not found."
  }
}

Field	Description
error.code	Error code. It is the same in every language, so branch on this value
error.message	Description you can show to users
error.details	Extra information, only for some errors

For example, an invalid request body names the first invalid field in error.details.property:

{
  "error": {
    "code": "INVALID_REQUEST_BODY_EXCEPTION",
    "message": "The request contains an invalid value.",
    "details": {
      "property": "keyword"
    }
  }
}

Request ID

Every response includes an X-YouViCo-Request-Id header with a 32-character hexadecimal ID:

X-YouViCo-Request-Id: 4bf92f3577b34da6a3ce929d0e0e4736

Log this value with failed requests, and you can include it when you report an error to us.

HTTP status codes

Status	Meaning
400 Bad Request	A field is missing or invalid, or the cursor is malformed
401 Unauthorized	The API key or OAuth access token is missing, invalid, or expired
403 Forbidden	You do not have permission for this action
404 Not Found	The resource does not exist, or you cannot reach it
409 Conflict	The request conflicts with the current state, such as a duplicate reaction
413 Content Too Large	The request body is too large
415 Unsupported Media Type	The request body is not sent as JSON
429 Too Many Requests	You exceeded the rate limit
500 Internal Server Error	Something went wrong on our side
503 Service Unavailable	The service is under maintenance

Common error codes

These can occur on any endpoint.

Code	Status	When it occurs
INVALID_REQUEST_BODY_EXCEPTION	400	The request body is invalid, or a cursor is malformed
INVALID_REQUEST_EXCEPTION	400	The request is invalid
INVALID_AUTHENTICATION_HEADER_EXCEPTION	400	The Authorization header is not in the Bearer YOUR_API_KEY format
INVALID_API_KEY_EXCEPTION	401	The API key does not exist or is no longer active
INVALID_ACCESS_TOKEN_EXCEPTION	401	The OAuth access token is invalid or has expired
ACCESS_DENIED_EXCEPTION	403	You do not have access to the resource
FORBIDDEN_SCOPE_EXCEPTION	403	The key or connection lacks the scope the endpoint needs
FORBIDDEN_ROLE_EXCEPTION	403	Your role does not allow this action
USER_SUSPENDED_EXCEPTION	403	The account is suspended
NOT_IN_WORKSPACE_EXCEPTION	403	You are not a member of the workspace
FORBIDDEN_STATUS_EXCEPTION	403	The workspace member is inactive
PROJECT_ARCHIVED_EXCEPTION	403	The project is archived and cannot be changed
ROUTE_NOT_FOUND_EXCEPTION	404	The URL path is not an endpoint
WORKSPACE_NOT_FOUND_EXCEPTION	404	The workspace does not exist
REQUEST_BODY_SIZE_LIMIT_EXCEEDED_EXCEPTION	413	The request body is too large
UNSUPPORTED_CONTENT_TYPE_EXCEPTION	415	The request body is not sent as application/json
RATE_LIMIT_EXCEEDED_EXCEPTION	429	You exceeded the endpoint's rate limit
INTERNAL_UNEXPECTED_EXCEPTION	500	An unexpected server error occurred
DATABASE_UNAVAILABLE_EXCEPTION	500	The request cannot be processed right now. Try again later
SERVICE_MAINTENANCE_EXCEPTION	503	The service is under maintenance