Guides Use cases API Changelog

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, card acceptance, and bank accounts.

Across all endpoints, you'll typically see the following response statuses:

  • 2xx responses for successful API calls
  • 4xx responses for errors with the input
  • 5xx Moov is in a degraded state; extremely rare

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 synchronous, 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 account ID 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 account ID 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.

Card acceptance

HTTP status code HTTP status message Description Error handling guidance
404 Not found No account with the specified account ID 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 account ID 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
Rate limits