> ## Documentation Index
> Fetch the complete documentation index at: https://docs.straddle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Straddle API response format

> Understand the JSON envelope for Straddle API responses, including the data, meta, and error fields, plus pagination metadata for list endpoints.

Understanding the structure of API responses is crucial for effectively integrating with the Straddle API. This guide outlines the standard format for successful requests, paginated responses, and error responses.

## Successful Requests

For successful requests, the Straddle API returns a JSON object with the following structure:

* `meta`: Contains metadata about the request.
* `response_type`: Indicates the type of data returned (eg "object" or "array").
* `data`: Contains the actual payload of the response.

### Example: Single Object Response

<CodeGroup>
  ```json JSON theme={null}
  {
    "meta": {
      "api_request_id": "f1b1b1b1-1b1b-1b1b-1b1b-1b1b1b1b1b1b"
    },
    "response_type": "object",
    "data": {
      "id": "1",
      "name": "John Doe",
      "email": "john.doe@gmail.com",
      "dob": "1980-01-01",
      "address": {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "NY",
        "zip": "12345"
      }
    }
  }
  ```
</CodeGroup>

### Key Points

* The `data` property contains the main payload.
* `response_type` is set to "object" for single item responses.
* Field names use whole words, except for common acronyms (e.g., dob, SSN, URL).
* IDs are represented as strings.

## Paginated Responses

For requests that return lists of data (e.g., a list of customers), the response structure is similar but includes pagination information:

* `data` contains an array of objects, typically with summarized information.
* `response_type` is set to "array".
* `meta` includes additional pagination-related information.

### Example: Paginated Response

<CodeGroup>
  ```json JSON theme={null}
  {
    "meta": {
      "api_request_id": "f1b1b1b1-1b1b-1b1b-1b1b-1b1b1b1b1b1b",
      "page_number": 4,
      "page_size": 50,
      "total_items": 1500,
      "sort_order": "asc",
      "sort_by": "name"
    },
    "response_type": "array",
    "data": [
      {
        "id": "c1b1b1b1-1b1b-1b1b-1b1b-1b1b1b1b1b1b",
        "label": "John Doe",
        "name": "John Doe",
        "email": "john.doe@gmail.com"
      },
      {
        "id": "a9b1b1b1-1b1b-1b1b-1b1b-1b1b1b1b1b1b",
        "name": "Steven Martin",
        "email": "steve@martinco.com"
      },
      {
        "id": "f6b1b1b1-1b1b-1b1b-1b1b-1b1b1b1b1b1b",
        "name": "John Doe",
        "email": "john.doe@gmail.com"
      }
    ]
  }
  ```
</CodeGroup>

### Pagination Metadata

The `meta` object in paginated responses includes:

* `page_number`: Current page number
* `page_size`: Number of items per page
* `total_items`: Total number of items across all pages
* `sort_order`: Sorting order ("asc" or "desc")
* `sort_by`: Field used for sorting

## Failed Requests

For failed requests, the Straddle API uses HTTP status codes to indicate the nature of the error:

* 4xx status codes: Used for client-side errors (e.g., validation errors, permission issues)
* 5xx status codes: Used for server-side errors

The response structure for errors is different from successful requests:

* There is no `data` property.
* `response_type` is set to "error".
* An `error` object provides details about the error.

### Example: Error Response

<CodeGroup>
  ```json JSON theme={null}
  {
    "meta": {
      "api_request_id": "f1b1b1b1-1b1b-1b1b-1b1b-1b1b1b1b1b1b"
    },
    "response_type": "error",
    "error": {
      "status": 400,
      "type": "/field_validation",
      "title": "Invalid input data",
      "detail": "The request contains invalid field values",
      "items": [
        {
          "reference": "#WS01",
          "detail": "Payment window has closed for the day."
        },
        {
          "reference": "representative/2/email",
          "detail": "Email address must be unique"
        },
        {
          "reference": "representative/3/email",
          "detail": "Email address must be unique"
        }
      ]
    }
  }
  ```
</CodeGroup>

### Error Object Structure

The `error` object in error responses includes:

* `status`: HTTP status code (integer)
* `type`: Predefined general type of error (e.g., "/field\_validation")
* `title`: Generic message for this type of issue
* `detail`: Specific message regarding this exact request
* `items`: Array of error objects with more specific details

Each error item in the `items` array contains:

* `reference`: Identifier for the error (e.g., field name, error code)
* `detail`: Detailed description of the specific error

## Best Practices for Handling Responses

1. **Check `response_type`**: Always check the `response_type` to determine how to parse the response.

2. **Handle Pagination**: When working with paginated responses, use the metadata to implement proper pagination in your application.

3. **Error Handling**: Parse the `error` object in failed requests to provide meaningful feedback to users or for debugging.

4. **Use `api_request_id`**: Log the `api_request_id` for all requests. This is crucial for troubleshooting and communicating with Straddle support.

5. **Parsing Data**: When working with successful responses, always access the payload through the `data` property.

## Conclusion

Understanding the Straddle API response format is key to building robust integrations. By following this structure, you can effectively handle successful responses, paginate through large datasets, and gracefully manage errors in your applications.

For more detailed information on specific API endpoints and their responses, please refer to our [API Reference](/api-reference) documentation.