Error Handling

The Segment Public API uses standard HTTP response codes to represent the state of an operation. Response codes in the 2xx range were completed successfully, while those in the 4xx and 5xx ranges indicate a problem. The API also uses a response envelope format that makes it easy to navigate through response details.

Status codes overview

Code Message Overview
200 OK A request was accepted and handled successfully.
201 Created A new resource was created successfully.
401 Unauthorized No authorization, or incorrect authorization provided for the resource.

This could mean:

- A missing API Token
- An invalid API token
- The provided API token does not have permission to access the resource.
404 Not found The requested resource does not exist or cannot be found.
409 Conflict There was a conflict when processing this request that prevented it from being fulfilled.
413 Payload too large The request body is larger than limits defined by the server.
422 Unprocessable entity The request contained invalid parameters and was not accepted.

This usually means the request was missing required parameters, or included parameters that did not pass validation.
429 Too many requests Too many sequential or concurrent requests to a specific resource or endpoint were made.
5xx Server error Segment was unable to serve the request due to an internal failure.

Response envelopes

The Segment Public API uses a consistent envelope format in all response bodies. This makes it easy to read the response data, and check for and handle any potential errors.

The following two examples illustrate the responses.

  data: {
    hello: 'world',
    // ... other keys and values
  "errors": [
      "type": "input-validation",
      "message": "\"id\" is required",
      "field": "id"

Responses will never contain both data and error keys.

The data object

An object that contains the successful response from an API call. Responses in the 2xx range always contain valid data, and conform to the SuccessResponse type specified above.

The following request and response pair shows a successful request and its response:

curl \
  --header 'Authorization: Bearer <token>'

A successful response always includes a data field.

  data: {
    warehouse: {
      id: '4w5kMU6vycSjfjt87k3pZB',
      workspaceId: '3i5paCz7b2MaaA8Wi7xXwe',
      enabled: true,
      // ...

The errors object

This section includes errors that prevented a request from completing. Responses in the 4xx and 5xx ranges always contain an errors array, as specified in the ErrorResponse type above, which describes the errors that prevented the request from finishing.

Given the following invalid request:

curl --request POST \
  --url \
  --header 'Authorization: Bearer <token> ' \
  --header 'Content-Type: application/json' \
  --data '{
    "warehouse": {}

The response includes a list of errors that contains all errors that occurred during the request:

HTTP/1.1 422 Unprocessable Entity
  "errors": [
      "type": "input-validation",
      "message": "\"metadataId\" is required",
      "field": "warehouse.metadataId"
      "type": "input-validation",
      "message": "\"settings\" is required",
      "field": "warehouse.settings"

The error object

All errors in the Segment Public API use a consistent format. They always include a type field, which explains the type of error encountered, and may include optional fields to provide extra information and metadata about the failure.

/** RequestError represents any error that could occur while executing a request. */
type RequestError = {
  /** The type of error (validation, server, conflict, etc) */
  type: string

  /** An optional error message attached to the error */
  message?: string

  /** An optional field that triggered the error */
  field?: string

  /** An optional extra data object that can be associated with this error */
  data?: object

The next section introduces Validation Errors, and explains how to handle and recover from requests that fail validation.