Response and error model

The Spring Boot API returns a shared JSON envelope named ApiResponse<T>.

Response envelope

Typical response fields are:

Field	Type	Meaning
success	boolean	Whether the request was handled successfully
code	number	Application-level status code, often aligned with HTTP status
message	string | null	Human-readable status or error message
data	T | null	The successful payload
timestamp	datetime	Response creation timestamp
error	object | null	Optional structured error details

Successful responses normally look like:

{
  "success": true,
  "code": 200,
  "data": {},
  "timestamp": "2026-04-12T12:34:56"
}

Error responses normally look like:

{
  "success": false,
  "code": 401,
  "message": "Authentication required",
  "timestamp": "2026-04-12T12:34:56"
}

Common HTTP statuses

HTTP status	Typical meaning in this repo
400	Validation failure, malformed JSON, missing parameter, or business-rule rejection
401	Missing or invalid authentication, including expired or invalid refresh token flows
403	Authenticated but not authorized
404	Resource or route not found
405	Method not allowed for an existing path
415	Unsupported media type
429	Rate limit or quota exceeded
500	Unhandled server-side error
507	Global storage limit exceeded

Current backend error behavior

Important details from the current exception mapping:

• Validation failures currently return 400 with a generic message such as Parameter validation failed
• Auth failures return 401
• Access control failures return 403
• Rate limits return 429 and may include Retry-After
• Unknown server failures return a generic System error

Rate limiting and quotas

Some protected operations are subject to rate or quota controls.

When a request is throttled:

• HTTP status is 429
• Retry-After may be present
• X-RateLimit-Remaining: 0 may be present for request-rate limits

Quota failures also use 429, but they represent product usage exhaustion rather than a short-lived request burst.

BFF proxy errors

The Next.js BFF can also generate non-backend responses before a request reaches Spring Boot:

Status	Message	Meaning
500	Proxy misconfigured	Required BFF env vars are missing
502	Upstream fetch failed	The BFF could not reach the backend
404	Not found	The browser requested a non-/api/bff/api/v1/* path

These BFF responses are plain JSON error objects, not the backend ApiResponse<T> envelope.