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
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
Pagination Metadata
Themeta
object in paginated responses includes:
page_number
: Current page numberpage_size
: Number of items per pagetotal_items
: Total number of items across all pagessort_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
- There is no
data
property. response_type
is set to “error”.- An
error
object provides details about the error.
Example: Error Response
Error Object Structure
Theerror
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 issuedetail
: Specific message regarding this exact requestitems
: Array of error objects with more specific details
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
-
Check
response_type
: Always check theresponse_type
to determine how to parse the response. - Handle Pagination: When working with paginated responses, use the metadata to implement proper pagination in your application.
-
Error Handling: Parse the
error
object in failed requests to provide meaningful feedback to users or for debugging. -
Use
api_request_id
: Log theapi_request_id
for all requests. This is crucial for troubleshooting and communicating with Straddle support. -
Parsing Data: When working with successful responses, always access the payload through the
data
property.