API Standards

Success response

Success and failure use different shapes that never mix. Tell one from the other by the HTTP status, never by a field in the body.

{
  "data": { "id": 1, "name": "Ada" }
}

With pagination

{
  "data": [ ... ],
  "meta": {
    "pagination": { "page": 2, "limit": 2, "totalItems": 7, "totalPages": 4 }
  }
}

• data is always present on a 2xx response that has a body. An empty list is [], never null.
• There is no error, code or message on a success response.
• meta is optional and only carries information outside the payload, never domain data.
• A DELETE that returns nothing answers 204 with no body.

Error response

The error object is always nested under error, so it can never be mistaken for a success payload.

{
  "error": {
    "code": 100001,
    "name": "USER_NOT_FOUND",
    "message": "user not found",
    "details": [
      { "field": "startDate", "reason": "required" }
    ]
  }
}

• code and name are stable. These are the only fields safe to branch on — neither changes once released.
• message is not stable. It follows the caller's language and its wording may change at any time, so never match on it; show it to the user instead.
• details is optional, used when one error has several specific causes — usually per-field validation failures. Its reason is aimed at developers and is not translated.
• Raw server error text, SQL, stack traces, hostnames and table names never appear in a response.

HTTP status

The status comes from the error definition, not from the handler. A failure never answers 200.

Languages

Only message is translated. The language is chosen in this order:

• The ?lang= query parameter, which beats the header so a client can force one language without touching device settings.
• The Accept-Language header, including quality values such as ko,en-US;q=0.8.
• en-US, the default, used when nothing matches.

A tag naming only a language matches its region, so ko resolves to ko-KR. An unknown language falls back to the default rather than producing an error. Supported: en-US, id-ID, ko-KR.

GET /api/v1/user/99
Accept-Language: ko-KR

404 Not Found
{
  "error": {
    "code": 100001,
    "name": "USER_NOT_FOUND",
    "message": "사용자를 찾을 수 없습니다"
  }
}

Pagination

Every list endpoint takes the same two query parameters.

Invalid pagination never produces an error: it is read as a request for the first page. The offset is computed on the server and is never accepted from the client. The response carries meta.pagination, never fields at the root of the body.

Error codes

Each module owns one block of 10,000 codes. A released code is never reused and a name is never renamed, so both are safe to store and branch on.

No error code matches that filter.