Error handling

Always check the HTTP status code first. It communicates the protocol-level outcome of the request, including invalid input, authentication failure, missing resources, and server failure. When the API rejects an otherwise valid request because of a registered business rule or capability, it returns HTTP 422 together with a standard Error Response body. Use the numeric code in that body to identify and handle the specific business error.

HTTP status codes

The token endpoint follows OAuth conventions and is separate from the protected business API response model. For HTTP 200, read the OAuth token response directly or verify code: 0 and read result for a protected endpoint.

HTTP status	Typical cases	How to interpret the response
200	Token issued; protected endpoint succeeded	Read the OAuth token response directly, or expect code: 0 and read result for a protected endpoint.
400	Malformed token request; unsupported OAuth input; invalid endpoint parameters	Correct the request before retrying.
401	Missing or invalid Client credentials or Bearer token	Correct or replace the credentials or token.
404	Resource not found or outside the token organization	Verify the resource identifier and organization assignment.
422	A protected endpoint reached a registered business error	Inspect the published numeric business code.
500	Unexpected service failure	Retry transient failures with backoff and retain the request_id.

Endpoint-specific HTTP statuses and response schemas are defined in the API reference.

Business error response

Business errors use HTTP 422 with the standard Open API business error envelope:

{
  "code": 2001,
  "message": "device history is not supported",
  "timestamp": "2026-07-15T10:00:00Z",
  "request_id": "req_device_history_001",
  "details": null
}

Use code for program logic. Do not parse message, because its wording may change. Record request_id with integration logs so Mango Power support can trace a failed request.

Business error codes

Open API business codes use a dedicated 2000–2999 range and are separate from Mango Power’s internal platform error codes. Published numbers are never reassigned to a different meaning.

Code	Name	Meaning
2000	REALTIME_NOT_SUPPORTED	The device does not support realtime data.
2001	HISTORY_NOT_SUPPORTED	The device does not support history data.
2002	HISTORY_TIME_ORDER_INVALID	start_at is not earlier than end_at.
2003	HISTORY_BUCKET_UNALIGNED	The requested time range is not aligned to the selected UTC bucket.
2004	HISTORY_RANGE_EXCEEDED	The requested time range exceeds the maximum for the selected interval.

This is the complete business error-code list. Future codes will be appended without changing existing numbers.