# Status codes

# HTTP status codes

The Trusted Twin API uses HTTP status codes (opens new window) to communicate if a request has been successfully processed or not:

  • Successful operations will return 2xx codes.
  • Operations that result in an error due to a problem on the client's side will return 4xx codes.
  • Operations that result in an error due to a problem in the Trusted Twin server will return 5xx codes.
Status code Message Description
200 OK Successful request and response.
201 Created The resource was successfully created.
400 Bad request The request was unacceptable, often due to missing a required parameter or malformed parameters.
401 Authentication required Authentication failed or was not provided.
403 Forbidden The user does not have permissions to perform the request.
404 Not found The requested resource does not exist.
500 Internal error The server encountered an internal error and was not able to complete the request.

# Error subcodes

All errors can be handled programmatically. The error response includes specific attributes and error subcodes that state the cause of the error.

Attribute Type Description
subcode string Unique subcode of the error.
trace string String identifying the specific error instance. Please reference the trace when contacting our support team to ensure the fastest resolution.
description string Description that states the cause of the error.

# Subcode examples

Below you will find a list of error subcodes. This list is not exhaustive.

Subcode Message Description
400141 quota_violation The body of the request or the Ledger exceeds 64 kB and is, as a result, too large to process.
400314 invalid_characters Characters in the body of the request are not UTF-8 encoded. Example response: "Request body contains invalid characters."
400358 idempotency_violation The operation has already been performed. Example response: "Twin already terminated.".
400415 not_a_valid_json The body of the request does not follow JSON syntax. You can use the JSON formatter and validator (opens new window) to check if the request is JSON compliant. Example response: "Request body is not a valid JSON.".
400589 request_format The format of the request is not correct. Example response: "body::description->__key__: string does not match regex ^[a-z_][0-9a-z_]{0,63}$".
400592 operation_order_violation Operations have not been conducted in correct order. Example response: "Remove User before removing a Role.".
400897 operation_not_allowed A User cannot grant permissions that are not included in the "statement" of their own role. Example response: "You cannot grant permissions that are not included in the 'statement' of your role: {}."
400926 field_required The request is missing a required field.
400979 service_disabled The service is not enabled for the Account. Example response: "Timeseries not enabled for Account". Please contact hello@trustedtwin.com for more details about enabling the service for your Account.
401000 unauthorized The User could not be authenticated. Example responses: "Invalid secret.", "Authorization header not provided.", "Operation not allowed.".
403535 access_forbidden The User does not have permission to access the requested resource. Example response: "No access to the resource(s): Not a Twin owner."
404653 not_found The resource could not be found in the system.
50000x internal_error The server encountered an internal error and was not able to complete the request.
500159 response_timeout A server is taking too long to reply to a data request made from another device.
500314 timeseries_no_connection Connection could not be established to the Timeseries database. Example response: "Could not connect to Timeseries database."