API Standards

Conventions

• Base path: /api/v1
• JSON request/response bodies
• ISO 8601 timestamps
• UUID identifiers
• Pagination: ?page=0&size=20

Standard Error Response

{
  "error": {
    "code": "PAYMENT_INSUFFICIENT_FUNDS",
    "message": "Insufficient available balance",
    "correlation_id": "uuid",
    "timestamp": "2026-01-15T10:30:00Z"
  }
}

HTTP Status Codes

Code	Usage
200	Success
201	Created
202	Accepted (async)
400	Validation error
401	Unauthenticated
403	Unauthorized
404	Not found
409	Conflict (idempotency)
429	Rate limited
500	Internal error