Error handling

After you submit an API call to Moov, you receive an HTTP response indicating whether or not the call was successful. This guide summarizes the various error codes you may see for transfers, capabilities, cards, and bank accounts. Broadly, you’ll see two types of HTTP responses:

2xx responses for successful API calls
4xx responses for errors

Transfers

HTTP status code	HTTP status message	Description	Error handling guidance
201	Created	Transfer was successfully created but an error occurred while getting the synchronous response. The asynchronous response object will be returned.	Moov’s internal services are in a degraded state and are unable to return the full transfer object as a response. The transfer was created but we aren’t able to generate a synch response so we return the async response here. You can attempt GET the transfer using the ID that’s returned. Note that if Moov’s services are still degraded, you will not be able to get the response if you attempted to use the transfer `GET` endpoint right after creating the transfer.
202	Accepted	A transfer or refund was successfully created but a timeout occurred while waiting for a synchronous response. Rail-specific details may be missing from the response object.	A timeout occurred with the payment network. To retrieve full rail-specific details at a later time, use the transfer GET endpoint.
400	Bad request	Invalid request, an error message will be available in the response body.	There was a problem with the request payload. The error message will provide specific details on what needs to be fixed.
409	Conflict	Attempted to create a transfer using duplicate X-Idempotency-Key header	Retry the request with a different X-Idempotency-Key header.
422	Unprocessable content	The request body could not be processed	The error message will let you know how long to wait (in milliseconds) before you can retry
429	Too many requests	Request was refused due to rate limiting	The error message will let you know how long to wait (in milliseconds) before you can retry

Accounts

HTTP status code	HTTP status messsage	Description	Error handling guidance
404	Not found	No account with the specified accountID was found	Double check the account ID and retry.
422	Unprocessable content	The request body could not be processed	There was a problem with the request payload. Check for required headers, whether or not you’re using a duplicate ID, and that you’re using a valid account type. The error message will provide specific details on what needs to be fixed.
429	Too many requests	Request was refused due to rate limiting	The error message will let you know how long to wait (in milliseconds) before you can retry

Capabilities

HTTP status code	HTTP status messsage	Description	Error handling guidance
404	Not found	No account with the specified accountID was found	Double check the account ID and retry.
409	Conflict	The request could not be completed due to a state conflict with the target resource	There are capability requirements that have not yet been met or incomplete KYC verification. The error message will provide specific details about which requirements have not yet been met.
429	Too many requests	Request was refused due to rate limiting	The error message will let you know how long to wait (in milliseconds) before you can retry.

Cards

HTTP status code	HTTP status message	Description	Error handling guidance
404	Not found	No account with the specified accountID was found	Double check the account ID and retry.
409	Conflict	Attempted to link card that already exists on the account	Double check the card number you were trying to link.
422	Unprocessable content	The supplied card appeared invalid or was declined by the issuer	Double check the card number you were trying to link or get in contact with the card issuer.
429	Too many requests	Request was refused due to rate limiting	The error message will let you know how long to wait (in milliseconds) before you can retry

Bank accounts

HTTP status code	HTTP status message	Description	Error handling guidance
404	Not found	No account with the specified accountID was found	Double check the account ID and retry.
409	Conflict	Unable to get bank name for routing number or duplicate bank account	Double check the routing number provided.
422	Unprocessable content	The request body could not be processed	There was a problem with the request payload. The error message will provide specific details on what needs to be fixed.
429	Too many requests	Request was refused due to rate limiting	The error message will let you know how long to wait (in milliseconds) before you can retry.