Handling Errors - Dwolla Developer Portal

Overview

When interacting with the Dwolla API, it’s essential to understand how error responses are handled. These error responses are communicated through standard HTTP status codes, which provide clear indications of the type of error encountered during an API request. In addition to the status code, the JSON response body will include a top-level error code, offering further insight into the nature of the error. To ensure consistency and easy integration, errors will have their own media type, closely aligned with the vnd.error spec.

Example HTTP 401 error

{
  "code": "InvalidAccessToken",
  "message": "Invalid access token."
}

Embedded errors

In cases where your API request encounters specific issues that can be corrected, the Dwolla API returns responses with a top-level error code of ValidationError. These responses serve as valuable feedback, indicating that there are validation errors present in your request. The response will include a message: “Validation error(s) present. See embedded errors list for more details.” The embedded errors list may contain one or more detailed error objects, providing specific information about the issues found during the request. Each _embedded error object includes the following parameters:

• code: A detailed error code indicating the nature of the problem.
• message: A human-readable description of the error.
• path: A JSON pointer to the specific field in the request that caused the issue.

Possible Error codes

Example HTTP 400 validation error

{
    "code": "ValidationError",
    "message": "Validation error(s) present. See embedded errors list for more details.",
    "_embedded": {
        "errors": [
            {
                "code": "Required",
                "message": "FirstName required.",
                "path": "/firstName",
                "_links": {}
            }
        ]
    }
}

Common errors

The table below outlines common errors across all API endpoints in Dwolla.