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.

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.

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 https://api.segmentapis.com/warehouses/4w5kMU6vycSjfjt87k3pZB \
  --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 https://api.segmentapis.com/warehouses \
  --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.