Error Handling

The Untether Labs API follows the RFC-9457 Problem Detail specification for error responses. This standardized format provides consistent, machine-readable error information to help you build robust applications.

A complete list of expected errors can be found in the Error Reference. Each endpoint in the API Reference documents the specific errors that it may return.

Error Response Structure#

All API errors return a JSON response with the following structure:

Error Response Structure

{
    "type": "https://developers.untetherlabs.com/errors#user-not-found",
    "status": 404,
    "title": "A specified user does not exist in the system.",
    "detail": "User with ID '123e4567-e89b-12d3-a456-426614174000' was not found."
}

Response Fields#

Standard HTTP response codes are always returned in addition to the error body.

typestring

Required

A URI that uniquely identifies the error type. Always use this field to identify and handle specific errors programmatically.

statusinteger

Required

The HTTP status code of the response (e.g., 400, 404, 500). This is always set in the actual HTTP response also.

titlestring

Required

A short, human-readable summary of the problem type.

detailstring

A human-readable explanation specific to this occurrence of the problem.

Additional fields (extensions) may be present depending on the specific error type. See the response documentation for specific endpoints for details on any extensions.

Error Identification#

Always use the type field to identify errors programmatically. The type contains the full URL path to the specific error documentation:

Error Identification Example

if (error.type === 'https://developers.untetherlabs.com/errors#user-not-found') {
    // Handle user not found
    console.log('User does not exist');
} else if (error.type === 'https://developers.untetherlabs.com/errors#validation') {
    // Handle validation error
    console.log('Input validation failed:', error.message);
}