Error handling

Effective error handling is crucial for building robust integrations with the Localpayment API. Understanding the different error types and their corresponding codes will help you diagnose issues promptly and implement appropriate solutions.

HTTP response codes

Localpayment utilizes standard HTTP status codes to indicate the success or failure of API requests:​

  • 200 OK: The request was successful.​
  • 400 Bad Request: The request was malformed or contained invalid parameters.​
  • 401 Unauthorized: Authentication failed or was not provided.​
  • 403 Forbidden: The request is understood, but it has been refused or access is not allowed.​
  • 404 Not Found: The requested resource could not be found.​
  • 500 Internal Server Error: An unexpected error occurred on the server.

Error response structure

In addition to HTTP status codes, Localpayment provides detailed error information within the response body. Each error includes a specific code and description, categorized as follows:​

When an error occurs, the API typically returns a JSON response with details about the problem. The exact structure may vary slightly depending on the specific error, but it generally includes the following:

  • status.code: A string representing the Localpayment-specific error code.
  • status.description: A brief description of the error.
  • status.detail: More detailed information about the error.
  • errors: (Sometimes) An array of error objects, especially for validation errors, where each object describes a specific issue.

Example error response (400 Bad Request)

{
  "status": {
    "code": "300",
    "description": "REJECTED",
    "detail": "Invalid param + [paymentMethod] + [Is mandatory]"
  },
  "errors": [
    {
      "code": "300",
      "description": "REJECTED",
      "detail": "Invalid param + [paymentMethod] + [Is mandatory]"
    }
  ]
}

Best Practices for Error Handling

  • Check HTTP Status Codes: Always examine the HTTP status code first to get a quick overview of the response.
  • Inspect the Error Response Body: If the HTTP status code indicates an error (4xx or 5xx), carefully inspect the JSON response body for the status, errors, and other details.
  • Log Errors: Implement robust error logging to record error details, which will help you debug and diagnose problems.
  • Inform the User Appropriately: Provide informative and user-friendly error messages to your users. Avoid exposing technical details.
  • Retry Mechanism: For transient errors (e.g., network issues, temporary server errors), consider implementing a retry mechanism with exponential backoff.

By understanding how Localpayment reports errors, you can build more resilient and user-friendly applications.