Errors

Our API uses standard HTTP response codes to show whether an API request was successful or if it failed. According to RFC 9457, we return errors in a structured way so you can easily understand what went wrong and how to address it. Below, you'll find information about common errors, their meanings, and tips for resolving them.

Understanding Error Responses

When there's an error, the API responds with a JSON document that provides details about the problem. This helps you identify the issue and correct it. An error response typically includes:

  • type: A link that identifies the type of error.
  • title: A short description of the error.
  • status: The HTTP status code associated with the error.
  • detail: More detailed information about the error.
  • instance: A link to the specific occurrence of the error.

We may also include additional information specific to the error type. These details give you a clearer picture of the issue. If you encounter any extra details you don't recognize, you can safely ignore them. This flexibility allows us to update and provide more information without affecting existing error handling.

HTTP Status Codes

Here are some HTTP status codes you might see:

  • 400 Bad Request: There's a problem with your request, usually a missing or incorrect parameter.
  • 401 Unauthorized: Your request is missing valid authentication credentials.
  • 403 Forbidden: You don't have permission to perform the requested action.
  • 404 Not Found: The resource you're looking for doesn't exist.
  • 409 Conflict: There's a conflict with the current state of the target resource.
  • 429 Too Many Requests: You've sent too many requests in a short period and have been throttled.
  • 500 Internal Server Error: An unexpected error occurred on our side, though this is quite rare.

Handling Errors

Errors on our side, especially those resulting in 500 series responses, are infrequent but can happen. Here's how you can address errors:

  • Ensure all required fields are included and correctly formatted.
  • Check that the data types of your parameters match what is expected.
  • Verify your authentication credentials are correct and have the appropriate permissions.

For 429 Too Many Requests, consider implementing a delay or a back-off strategy before retrying your request to avoid further limitations.

Example Error Response

Here's an example of a validation error response:

{
  "type": "https://api.superpayments.com/errors/request_validation_error",
  "title": "Bad Request",
  "status": 400,
  "detail": "Request validation failed",
  "instance": "trace-id",
  "errors": [
    {
      "path": "amount",
      "message": "Number must be greater than or equal to 1"
    }
  ]
}

Conclusion

Handling errors effectively is key to a successful integration. By understanding our error messages, including any additional details provided, and familiarizing yourself with common HTTP status codes, your application can better respond to different scenarios. For ongoing issues or further assistance, don't hesitate to contact our support team.