​
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

CodeDescription
Required{field name} is required. For example, null or empty string in required field.
Invalid{field name} invalid.
InvalidFormat{field name} is not in a valid format. For example, characters in the amount field.
DuplicateDuplicate resource error. For example, A customer with the specified email already exists.
ReadOnlythis field is not allowed to be modified
NotAllowedvalue, while valid/exists, is not allowed to be used
Restrictedaccount or customer restricted from this activity
InsufficientFundsused on source or destination fields of transfer endpoint
RequiresFundingSourceused on destination field of transfer endpoint to indicate customer needs a bank
FileTooLargeused on document upload

​
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.
HTTP StatusError CodeDescription
400BadRequestThe request body contains bad syntax or is incomplete.
400ValidationErrorValidation error(s) present. See embedded errors list for more details. (See above)
401InvalidCredentialsMissing or invalid Authorization header.
401InvalidAccessTokenInvalid access token.
401ExpiredAccessTokenGenerate a new access token using your client credentials.
401InvalidAccountStatusInvalid access token account status.
401InvalidApplicationStatusInvalid application status.
401InvalidScopesMissing or invalid scopes for requested endpoint.
403ForbiddenThe supplied credentials are not authorized for this resource.
403InvalidResourceStateResource cannot be modified.
404NotFoundThe requested resource was not found.
405MethodNotAllowed(varies)
406InvalidVersionMissing or invalid API version.
500ServerErrorA server error occurred. Error ID:
500RequestTimeoutThe request timed out.