Request and response shape

Clients write code against your field names, so pick conventions once and apply them everywhere. Use one naming style (snake_case or camelCase, not both). Send times as ISO 8601 strings in UTC: "2026-10-23T14:05:00Z". Send money as an integer in minor units plus a currency: {"amount": 1999, "currency": "EUR"} for €19.99; floating-point numbers can't represent most decimal amounts exactly.

Return ids as strings, even if they're numbers today: JavaScript loses precision on integers above 2⁵³, and you may switch to UUIDs later. And wrap lists in an object, {"data": […], "next_cursor": …}, so you can add paging fields later without breaking clients.

GET /orders/42
→ 200 OK
{
  "id": "42",
  "status": "paid",
  "total": {"amount": 1999, "currency": "EUR"},
  "created_at": "2026-10-23T14:05:00Z",
  "customer_id": "7"
}

GET /orders
→ 200 OK
{"data": [ … ], "next_cursor": "eyJpZCI6NDJ9"}

Every error from your API should have the same shape, so a client writes one error handler. The IETF standard for this is Problem Details (RFC 9457), sent as Content-Type application/problem+json. Its fields, all optional: type (a URI identifying the kind of error), title (short, human-readable), status (the HTTP code), detail (this occurrence), instance (which request). You may add your own fields, such as a list of invalid fields.

Two rules make errors useful. Give a stable machine-readable code (the type), so clients branch on it instead of parsing English. And never put stack traces, SQL or internal hostnames in the body: they help attackers, not users.

POST /bookings
{"check_in": "2026-11-05", "check_out": "2026-11-03"}

→ 422 Unprocessable Content
Content-Type: application/problem+json
{
  "type": "https://api.example.com/errors/invalid-dates",
  "title": "Invalid dates",
  "status": 422,
  "detail": "check_out must be after check_in",
  "errors": [{"field": "check_out", "message": "must be after check_in"}]
}