Error Handling Guide

This section elaborates on the error codes returned by our API endpoints, aiming to equip developers with the knowledge needed to build resilient applications that gracefully handle errors, thus ensuring a seamless user experience.

Understanding HTTP Status Codes

Our API adheres to standard HTTP status codes to signify the outcome of an API request. Familiarity with these codes is crucial for effective error handling:

• 200 OK: The request was successful.
• 201 Created: The request was successful, and a new resource was created.
• 204 No Content: The request was successful but does not return any content.
• 400 Bad Request: The server could not process the request due to invalid syntax. Check your request format and retry.
• 401 Unauthorized: The request lacks valid authentication for the target resource. Ensure that your authentication credentials are correct and have the necessary permissions.
• 403 Forbidden: The server understood the request but refuses to authorize it. Verify your account's permissions and scopes.
• 404 Not Found: The requested resource could not be found. Ensure the resource exists and your request URL is correct.
• 409 Conflict: Request conflict with the current state of the target resource.
• 429 Too many requests: Too Many Request, API rate limit exceeded, please try after sometime.
• 500 Internal Server Error: The server encountered an unexpected condition. If this error persists, please contact our support team.
• 503 Service Unavailable: The server is currently unable to handle the request due to temporary overloading or maintenance. Retry the request after some time.

Custom Error Codes and Resolutions

To further assist in diagnosing issues, our API provides detailed custom error codes alongside HTTP status codes:

HTTP Status Code	Error Code	Message	Suggested Action
400	4000001	Invalid partnerId	Verify the partnerId parameter for correctness.
400	4000002	Missing purchaseRef	Ensure the purchaseRef parameter is included in the request.
400	4000003	Missing csuId	Include the csuId parameter in your request.
400	4000004	Invalid request data	Review and correct your request payload.
400	4000005	Unsupported product ID	Check if the product ID is valid and supported.
400	4000006	Unable to get user data for given csuId	Ensure the csuId is correct and the user exists.
400	4000007	Activation link already redeemed	Create a new activation link as the current one has already been redeemed.
400	4000008	Activation link was cancelled	Create a new activation link as the current one has already been cancelled.
401	4010001	Missing Auth Token	Include a valid authentication token in your request header.
401	4010002	Invalid/Expired Auth Token	Check the token's validity or refresh it before retrying.
401	4010003	Jwt not decodable	Ensure the JWT is correctly formatted and encoded.
401	4010004	Missing jwt header with key id	Include the JWT header with the key ID in your token.
401	4010005	Jwt Unknown Error	Verify the JWT's structure and encoding; contact support if the issue persists.
409	4090001	Purchase reference not unique	Ensure that the purchaseRef is unique.
429	4290001	Too many requests, please retry after some time	Ensure that the next subsequent call is not immediate.
403	4030001	Auth Token missing required scope	Ensure your token has the necessary scopes for this operation.
404	4040001	Resource Not Found	Double-check the requested resource's existence and ID.
500	5000001	Internal Server Error	If this error persists, contact our technical support team.
500	5000002	Unable to get user e-mail address	Verify the user's information and try again.
500	5000003	Invalid productId	Check the productId for correctness and validity.
500	5000004	Unable to find product for given productId	Ensure the productId is correct and exists in the product catalog.
500	5000005	Purchase creation failed	Review the purchase details and try again.

Note:

• For 400 Bad Request errors, reviewing the request's structure and parameters is often the key to resolution.
• 401 Unauthorized and 403 Forbidden statuses typically indicate issues with authentication or authorization; verify your credentials and permissions accordingly.
• 429 Too Many Requests errors suggest exceeding the API rate limit; consider implementing rate limiting on your end to prevent this.
• Persistent 500 Internal Server Error occurrences necessitate direct communication with our support to identify and resolve underlying issues.

Support

For additional guidance or support, please refer to our Developer Guides or contact our Support Team.