Error Handling

The API provides structured JSON error responses for business/domain errors and a minimal response for some auth failures.

Structure

{
  "message": "Human readable description",
  "code": -2000
}

Fields:

message: Localized (currently English) description derived from the server-side error code.
code: Stable integer identifier (negative values reserved by platform).

HTTP	Typical Cause	Notes
400	Validation / domain errors	Includes codes like `InvalidData`, `UnknownCounterType`
401	Missing or invalid bearer token	May have empty body or error JSON depending on stage
403	Access denied to a resource	Token valid but lacks permission
404	Resource not found	Code: `NotFound`
429	Rate limit exceeded	Body may be generic; implement retry with backoff
500	Unhandled internal error	Code: `Unknown`

Code	Name	Message
-1000	Unknown	An unknown error occurred. Please contact the support.
-1100	NotFound	The requested resource was not found.
-2000	InvalidData	The request was invalid or cannot be served. Please check the request and try again.
-2010	UnknownCounterType	The counter type does not exist.
-2011	InvalidMode	The mode is invalid for this type of counter.
-2020	InvalidStartDate	The start date is invalid.
-2021	InvalidEndDate	The end date is invalid.
-2030	DisplayNameInvalidLength	The display name must be between 5 and 40 characters long.
-2040	InvalidOperationForCounterType	The operation is invalid for this type of counter.

Code	Retry?	Strategy
Unknown	Yes (limited)	Retry with exponential backoff; report if persists
NotFound	No	Verify resource id
InvalidData	No	Fix request payload
InvalidMode / UnknownCounterType	No	Adjust client logic
Rate limit (429)	Yes	Backoff 1s,2s,4s,8s.. max 30s

Clients should ignore unknown properties in error objects. Future extensions may add: traceId, details[], or fields[].

In integration test environments a 500 (Unknown) may include stack trace fields to help automated diagnostics (not present in production).

Last modified: 01 October 2025