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

JSON

{
  "meta": {
    "api_request_id": "f1b1b1b1-1b1b-1b1b-1b1b-1b1b1b1b1b1b"
  },
  "response_type": "object",
  "data": {
    "id": "1",
    "name": "John Doe",
    "email": "[e-mail]",
    "dob": "1980-01-01",
    "address": {
      "street": "123 Main St",
      "city": "Anytown",
      "state": "NY",
      "zip": "12345"
    }
  }
}

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

JSON

{
  "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": "[e-mail]"
    },
    {
      "id": "a9b1b1b1-1b1b-1b1b-1b1b-1b1b1b1b1b1b",
      "name": "Steven Martin",
      "email": "[e-mail]"
    },
    {
      "id": "f6b1b1b1-1b1b-1b1b-1b1b-1b1b1b1b1b1b",
      "name": "John Doe",
      "email": "[e-mail]"
    }
  ]
}

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

JSON

{
  "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"
      }
    ]
  }
}

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 documentation.