API Error Handling

The AMM API utilizes standard HTTP status codes to communicate the result of a request. Familiarity with these codes and their meanings is crucial for efficient error handling in your applications.

Before proceeding with using the AMM API, it is highly recommended that the AMM is upgraded to 2.17.5+, so that all the developed API features are available. If you are using an AMM version previous to 2.17.5, please review the release notes as to any API feature exceptions.

Below are some common error codes you might encounter while interacting with the AMM API, along with suggested handling approaches.

400 Bad Request

This status code indicates that the server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

Handling

• system.invalid.data.param: This error indicates an issue with the provided ids or idPrefix parameters in the /api/v1/systems/groups/{groupID}/data endpoint. Verify that the stat keys or prefixes are valid and correctly spelled.
• lastdata.incompatible.parameters: Returned when both ids and idPrefix parameters are present in the request for /api/v1/systems/groups/{groupID}/data endpoint. Only one of these parameters should be used at a time.
• lastdata.empty.parameters: Occurs if the idPrefix parameter is provided but empty in the request for /api/v1/systems/groups/{groupID}/data endpoint. If no specific prefix is needed, omit the parameter entirely.
• aggregation.too.many.targets: This error signifies that the request exceeds the maximum number of gateways allowed for retrieval in a single API call. Adjust your request to retrieve data in smaller batches, respecting the configured limit (default is 100 gateways).
• aggregation.too.many.data: The request exceeds the maximum number of stats allowed per gateway for a single API call to /api/v1/systems/groups/{groupID}/data endpoint. Limit the number of stats requested per gateway to stay within the configured threshold (default is 20 stats per gateway).
• system.unknown: This error, specific to the /api/v1/systems/{uid}/data endpoint, indicates that no gateway matching the provided UID (ESN) was found. Verify the accuracy of the UID (ESN).
• Carefully examine the request parameters and payload for errors.
• Refer to the API documentation for proper usage and parameter formatting.
• Implement input validation on the client side to prevent invalid requests.

401 Unauthorized

This status code means the request requires user authentication. The response must include a WWW-Authenticate header field containing a challenge applicable to the requested resource.

Handling

• Initiate the appropriate OAuth 2.0 flow to obtain a valid access token.
• Include the access token in the Authorization header of subsequent requests.
• Ensure that the access token hasn’t expired. If it has, use the refresh token to obtain a new access token.
• Check for potential issues with the client ID and secret used for authentication.

403 Forbidden

The server understood the request but refuses to authorize it.

Handling

• Verify the user’s permissions and ensure they have the necessary privileges to access the requested resource.
• Check if API access is disabled at the API client, customer group, or AMM user level. You might need to enable API access or adjust permissions accordingly.

408 Request Timeout

The server timed out waiting for the request.

Handling

• Optimize the client-side code to reduce request processing time.
• Consider increasing the timeout threshold on the server side if necessary and feasible.

429 Too Many Requests

Indicates that the user has sent too many requests in a given amount of time (rate limiting).

Handling

• Implement a retry mechanism with exponential backoff to handle rate limiting.
• Consider adjusting the API usage limits for the affected group, if possible.

Additional Considerations

• group.not.found.or.insufficient.privileges: For /api/v1/systems/groups/{groupID}/data endpoint, ensures that the groupId exists and that the user has sufficient privileges to access it.
• Invalid Grant: This error typically arises in the Resource Owner Flow when invalid end-user credentials are provided. Verify the username and password used for authentication.
• Invalid refresh token: This error message appears when attempting to refresh an access token using an invalid refresh token.

General Error Handling Tips

• Log Errors: Maintain detailed logs of errors encountered, including timestamps, HTTP status codes, error messages, and relevant request details. This information is invaluable for debugging and troubleshooting.
• User-Friendly Error Messages: When displaying error messages to users, avoid exposing technical details that might be confusing or sensitive. Instead, provide clear and concise messages that guide users towards resolving the issue.
• Graceful Degradation: Design your application to handle errors gracefully, allowing for partial functionality or alternative workflows when certain API calls fail. This prevents complete application breakdowns in case of API errors.