Error Handling

When interacting with the POS Hub API, your application may receive various HTTP status codes that indicate whether a request was successful or if an error occurred. This document provides a detailed overview of each relevant error code—what it means, why it occurs, and how you should handle it within your integration.

Below are some of the most common response codes you may encounter, along with recommended steps to resolve or recover from each scenario.

Overview of Error Responses

The POS Hub API always responds in JSON format, even when an error occurs. An error response typically contains the following fields (though the exact structure may vary based on the endpoint):

{
  "error": "A short description of what went wrong"
}

• error: A human-readable message describing the error.

When you receive an error, always log the error message and, if possible, the full response body. This information can help you diagnose the issue and determine the appropriate course of action.

HTTP Status Codes

400 Bad Request

Meaning:
This status code indicates that something about the request itself was invalid or malformed. Common causes include:

• JSON syntax errors.
• Missing required fields in the request body.
• Invalid query parameters or path variables.
• Data types or formats that do not match the API specification.

How to Handle:

1. Validate Input: Check that your request body follows the correct JSON structure and that all required fields are provided.
2. Correct Formatting Issues: Ensure data types match what the endpoint expects (e.g., strings where strings are required, integers where integers are required, and so on).
3. Retry After Fixes: Once you correct the request syntax or the payload, resend the request.

401 Unauthorized

Meaning:
This error is returned when credentials are missing, invalid, or have expired. It typically indicates that the user or application token is not recognized by the POS Hub platform.

How to Handle:

1. Obtain or Refresh Token:
   • If you are using OAuth2, ensure you have included a valid bearer token in the Authorization header (e.g., Authorization: Bearer <access_token>).
   • If your token is expired, use the refresh token flow to obtain a new access token.
2. Confirm Credentials:
   • Double-check that the client ID and secret are correct (where relevant).
   • Verify that the username and password (for password grant flow) or the token request parameters (for client_credentials/authorization_code) are accurate.
3. Re-authenticate: If necessary, prompt the user to log in again or reinitiate the token exchange process.

403 Forbidden

Meaning:
The request was understood by the server, but the user or application does not have the necessary permissions or scope to access the resource. This often occurs when the access token has insufficient privileges for the endpoint being called.

How to Handle:

1. Review Scopes or Permissions:
   • Check whether your application has been granted the required scope (e.g., resellers.read, catalogs.write, etc.).
   • Make sure the correct scopes were requested when generating the token.
2. Confirm User/Role Permissions:
   • If you’re using user-level access (password grant), verify the user’s assigned role and the permissions associated with that role.
3. Request Elevation:
   • If your application genuinely needs to perform this operation, contact the POS Hub team or an administrator to request additional privileges.

500 Internal Server Error

Meaning:
An unexpected error occurred on the POS Hub server. This typically indicates that an exception or unhandled scenario happened on the backend.

How to Handle:

1. Retry or Implement a Backoff:
   • Sometimes, transient conditions can cause 500 errors. A brief delay before retrying may resolve the issue.
2. Review Request:
   • Confirm that the request was not excessively large or malformed in a way that triggered a server-side exception.
3. Contact Support:
   • If the error persists across multiple retries and you cannot identify any issue in your request, reach out to POS Hub support with logs or request details for further assistance.

502 Bad Gateway

Meaning:
This status code indicates that POS Hub, acting as a gateway or proxy, received an invalid response from an upstream server or service. It can also occur if the POS Hub is temporarily unable to connect to an internal service or external provider.

How to Handle:

1. Check Service Status:
   • Ensure that any external systems you rely on (e.g., third-party integrations) are operational.
2. Retry:
   • Like 500-level errors, 502 errors can often be transient. Implement a delay before retrying.
3. Contact Support:
   • If the issue continues, provide your request logs to the POS Hub support team. They can investigate whether an upstream dependency is failing or if there is a network routing issue.

General Troubleshooting Tips

• Log Everything: Record request URLs, headers, and body payloads, as well as full error responses. This data is invaluable for diagnosing issues.
• Use Test Environments: Wherever possible, test requests in a sandbox environment or with sample data before making production changes.
• Leverage Retries with Backoff: For 5xx errors (e.g., 500, 502), set up exponential backoff policies to avoid hammering the server with rapid-fire retries.
• Stay Up to Date: Review the latest documentation or release notes to ensure you are aware of any endpoint changes or new error codes.

By carefully handling these status codes and adhering to best practices, you can build a more resilient, user-friendly integration with the POS Hub API. If you have any doubts or difficulties, don’t hesitate to contact the POS Hub support team for additional guidance.