Response Format
All API responses use a consistent JSON envelope with a data or error field and a meta object.
Success response
Single-resource responses wrap the result in a data field:
{
"data": {
"id": "00000000-0000-0000-0000-000000000001",
"status": "pending"
},
"meta": {
"request_id": "req_0000000000000001"
}
}List response
List endpoints wrap results in a data array and include pagination metadata:
{
"data": [
{ "id": "00000000-0000-0000-0000-000000000001", "status": "paid" },
{ "id": "00000000-0000-0000-0000-000000000002", "status": "pending" }
],
"meta": {
"pagination": {
"total": 47,
"limit": 20,
"offset": 0,
"has_more": true
},
"request_id": "req_0000000000000002"
}
}Error response
Errors use the same envelope shape with an error field instead of data:
{
"error": {
"code": "not_found",
"message": "invoice not found",
"details": []
},
"meta": {
"request_id": "req_0000000000000003"
}
}See Errors for the full list of error codes and when each is returned.
The meta.request_id field
Every response includes meta.request_id. Include this value in support tickets so the halfin team can locate the corresponding server trace immediately.