Overview

Orum uses HTTP status codes to indicate the success or failure of your API requests. If an API request fails due to an issue with authentication, authorization, or request validation, Deliver will synchronously return an HTTP status code, error code, and message.

Note:
Some errors cannot be caught synchronously at the time of the API request. The below errors will be sent via webhooks in the status_reasons object:

  • Errors that stem from payment processors: Payment rejections and returns. See transfer status reasons for more information.
  • Verification errors: Failure to verify a Person. See person status reasons for more information.

Error Schema and Examples

Synchronous errors contain an error_code and a message.

{
  "error_code": "missing_first_name",
  "message": "First name is required. Accepted values are letters, spaces, hyphens, apostrophes, periods, and diacritics."
}

Authentication and Authorization Errors

Below are the errors caused by failing to include a valid auth token or API key in Deliver request headers.

HTTP status codeError codeError message
401unauthorizedAuth token is missing, invalid or expired. Pass the token received from the /authenticate or /refresh endpoints. To pass the token, send: --header 'Authorization: Bearer {token}'. The auth token expires after one hour. Refresh the token using the /refresh endpoint.

Token Errors

Errors returned by the /authenticate and /refresh endpoints.

HTTP status codeError codeError messageIssue
400missing_nameId or name is required. Pass your API credential id.Not including your API credential id in your request to the /authenticate endpoint.
400missing_passwordSecret is required. Pass your API credential secret.Not including your API credential secret in your request to the /authenticate endpoint.
401unauthorizedName/id or secret is invalid.Passing a API credential id or secret that does not exist or is invalid to the /authenticate endpoint.
401unauthorizedThe refresh token has expired. Obtain a new refresh token using the /authenticate endpoint.Passing an expired refresh token to the /authenticate endpoint. The refresh token is valid for 30 days – after 30 days, obtain a new token using the /authenticate endpoint.
401unauthorizedRefresh token is invalid. Pass the refresh token received from the /authenticate endpoint.Passing an invalid refresh token to the /refresh endpoint.
400missing_refresh_tokenRefresh token is required. Pass the refresh token received from the /authenticate endpoint.Not including the refresh token in a call to the /refresh endpoint.

Persons Errors

HTTP status codeError codeError message
404unknown_idId is unknown. Pass the Orum-generated id for the person in the id path parameter.
400missing_customer_reference_idCustomer reference id is required. Pass a unique customer reference id.
400missing_customer_reference_idCustomer reference id is required. Pass the customer reference id used when creating the person.
400duplicate_customer_reference_idResource already exists with provided customer reference id. Pass a unique customer reference id.
400invalid_customer_reference_idCustomer reference id is invalid. Pass a unique customer reference id with type string.
400invalid_customer_reference_idCustomer reference id is invalid. Pass the customer reference id for the person.
400invalid_customer_reference_idCustomer reference id cannot be changed.
400missing_first_nameFirst name is required. Accepted values are letters, spaces, hyphens, apostrophes, periods, and diacritics.
400invalid_first_nameFirst name is invalid. Accepted values are letters, spaces, hyphens, apostrophes, periods, and diacritics.
400invalid_middle_nameMiddle name is invalid. Accepted values are letters, spaces, hyphens, apostrophes, periods, and diacritics.
400missing_last_nameLast name is required. Accepted values are letters, spaces, hyphens, apostrophes, periods, and diacritics.
400invalid_last_nameLast name is invalid. Accepted values are letters, spaces, hyphens, apostrophes, periods, and diacritics.
400missing_date_of_birthDate of birth is required. Valid format is YYYY-MM-DD.
400invalid_date_of_birthDate of birth is invalid. Valid format is YYYY-MM-DD.
400missing_addressesAddresses array is required. Provide an address of type “home” for the person.
400invalid_addressesAddresses array is invalid. Pass an array containing an address object.
400missing_addresses_typeAddress type is required. Pass type "home" for a person resource.
400invalid_addresses_typeAddress type is invalid. Valid type for person is "home".
400missing_address1Address1 is required.
400invalid_address1Address1 is invalid. Pass a string value.
400invalid_address2Address2 is invalid. Pass a string value.
400missing_cityCity is required.
400invalid_cityCity is invalid. Pass a string value.
400missing_stateState is required. Pass the two-character state code of the address.
400invalid_stateState is invalid. Pass the two-character state code of the address.
400missing_countryCountry is required. Only valid country code is "US".
400invalid_countryCountry is invalid. Only valid country code is "US".
400missing_zip5Zip5 is required. Expecting a 5-digit numeric zip code.
400invalid_zip5Invalid zip5. Expecting a string value of a 5-digit numeric zip code. Example: “10055”
400invalid_contactsContacts array is invalid. Pass an array of contact information containing phone and/or email contact types.
400missing_contacts_typeType field is required. Valid types are "phone" or "email".
400invalid_contacts_typeType field is invalid. Valid type is "phone" or "email".
400duplicate_contacts_typeContact types are duplicated. Only one contact for each type "phone” or “email” is allowed.
400invalid_phone_valuePhone number is invalid. Pass a valid 10-digit US phone number.
400missing_contacts_valueValue for contact type is missing. For type “phone”, pass a valid 10-digit US phone number. For type “email”, pass valid email. Example: [email protected]
400invalid_social_security_numberSocial security number is invalid.
400invalid_metadataMetadata must be a valid JSON object.

Businesses Errors

HTTP status codeError codeError message
400missing_customer_reference_idCustomer reference id is required. Pass a unique customer reference id.
400missing_customer_reference_idCustomer reference id is required. Pass the customer reference id for the business.
404unknown_idId is unknown. Pass the Orum-generated id for the business in the id path parameter.
400duplicate_customer_reference_idResource already exists with the provided customer reference id.
400invalid_customer_reference_idCustomer reference id is invalid. Pass a string value.
400invalid_customer_reference_idCustomer reference id is invalid. Pass the customer reference id for the business.
400invalid_customer_reference_idCustomer reference cannot be changed.
400missing_legal_nameLegal name is required. Accepted values are alphanumeric characters, spaces, hyphens, apostrophes, periods and diacritics.
400invalid_legal_nameLegal name is invalid. Accepted values are alphanumeric characters, spaces, hyphens, apostrophes, periods and diacritics.
400invalid_business_nameBusiness name is invalid. Accepted values are alphanumeric characters, spaces, hyphens, apostrophes, periods and diacritics.
400invalid_entity_typeEntity type is invalid. Valid entity type is "sole_proprietorship", "partnership", "limited_liability_partnership", "limited_liability_company", "c_corporation", "s_corporation", "b_corporation", or "nonprofit_corporation".
400missing_tax_idTax id is required. Expecting 9-digit numeric id.
400invalid_tax_idInvalid tax id. Expecting 9-digit numeric id.
400missing_tax_id_typeTax id type is required. Valid tax id type is "tin" or "ein".
400invalid_tax_id_typeTax id type is invalid. Valid tax id type is "tin" or "ein".
400invalid_account_holder_nameAccount holder name is invalid. Accepted values are letters, spaces, hyphens, apostrophes, periods and diacritics.
400invalid_incorporation_dateIncorporation date is invalid. Expecting format YYYY-MM-DD.
400missing_addressesAddresses array is required. Provide an address of type “legal” for the business.
400invalid_addressesAddresses array is invalid. Pass an array containing an address object.
400missing_addresses_typeAddress type is required. Pass type "legal" for a business resource.
400invalid_addresses_typeAddress type is invalid. Valid type for business is "legal".
400missing_address1Address1 is required.
400invalid_address1Address1 is invalid. Pass a string value.
400invalid_address2Address2 is invalid. Pass a string value.
400missing_cityCity is required.
400invalid_cityCity is invalid. Pass a string value.
400missing_stateState is required. Pass the two-character state code of the address.
400invalid_stateState is invalid. Pass the two-character state code of the address.
400missing_countryCountry is required. Only valid country code is "US".
400invalid_countryCountry is invalid. Only valid country code is "US".
400missing_zip5Zip5 is required. Expecting a 5-digit numeric zip code.
400invalid_zip5Invalid zip5. Expecting a string value of a 5-digit numeric zip code. Example: “10055”
400invalid_contactsContacts array is invalid. Pass an array of contact information containing phone, website, and/or email contact types.
400missing_contacts_typeType field is required. Valid types are "phone", "website" or "email".
400invalid_contacts_typeType field is invalid. Valid type is "phone", "website" or "email".
400duplicate_contacts_typeContact types are duplicated. Only one contact for each type “phone”, “website” or “email” is allowed.
400invalid_phone_valuePhone number is invalid. Pass a valid 10-digit US phone number.
400missing_contacts_valueValue for contact type is missing. For type “phone”, pass a valid 10-digit US phone number. For type “website”, pass a website with a valid top-level domain. For type “email”, pass a valid email. Example: [email protected]

External Account Errors

HTTP status codeError codeError message
400missing_account_reference_idAccount reference id is required. Pass a unique account reference id.
400missing_account_reference_idAccount reference id is required. Pass the external account’s account reference id.
400unknown_account_reference_idEnterprise does not have associated external account. Create an external account for the enterprise.
400invalid_account_reference_idAccount reference id is invalid. Pass a string value.
400invalid_account_reference_idAccount reference id is invalid. Pass the account reference id for the external account.
404unknown_idId is unknown. Pass the Orum-generated id for the external account in the id path parameter.
400duplicate_account_reference_idResource already exists with the account reference id.
400missing_customer_reference_idCustomer reference id for the external account’s associated person or business is required.
400invalid_customer_reference_idCustomer reference id is invalid. Pass a string value.
400invalid_customer_reference_idUnable to find associated person or business by customer reference id.
400missing_customer_resource_typeCustomer resource type is required. Valid customer resource type is “person”, “business” or “enterprise”.
400invalid_customer_resource_typeCustomer resource type is invalid. Valid customer resource type is “person”, “business” or “enterprise”.
400missing_account_typeAccount type is required. Valid account type is "checking" or "savings".
400invalid_account_typeAccount type is invalid. Valid account type is "checking" or "savings".
400missing_routing_numberRouting number is required. Pass a 9-digit routing number.
400invalid_routing_numberRouting number is invalid. Pass a 9-digit routing number.
400missing_account_numberAccount number is required. Pass an account number with 17 digits or fewer.
400invalid_account_numberAccount number is invalid. Pass and account number with 17 digits or fewer.
400missing_account_holder_nameAccount holder name is required.
400invalid_account_holder_nameAccount holder name is invalid. Accepted values are letters, spaces, hyphens, apostrophes, periods and diacritics.

Transfer Errors

HTTP status codeError codeError message
400missing_transfer_reference_idTransfer reference id is required. Pass a unique transfer reference id.
400invalid_transfer_reference_idTransfer reference id is invalid. Pass a unique transfer reference id with type string.
400missing_source_and_destinationSource and/or destination is required. To make an account-to-account or deposit transfer, pass both a source and destination object. To make a payout, pass only a destination object. To make a direct debit, pass only a source object.
400missing_source_account_reference_idAccount reference id for source is required. Pass the account reference id for the source external account.
400missing_destination_account_reference_idAccount reference id for destination is required. Pass the account reference id for the destination external account.
400missing_source_customer_reference_idCustomer reference id for source is required. Pass the customer reference id for the person or business associated with the source external account.
400missing_destination_customer_reference_idCustomer reference id for destination is required. For a payouts or A2A use case, pass the customer reference id for the person or business associated with the destination external account. For a deposits use case, pass your enterprise name.
400invalid_source_customer_reference_idCustomer reference id for source is invalid. Pass the customer reference id for the person or business associated with the source external account.
400invalid_source_account_reference_idAccount reference id for source is invalid. Pass the customer reference id for the person or business associated with the source external account.
400invalid_destination_account_reference_idAccount reference id for destination is invalid. Pass the account reference id for the destination external account.
400invalid_destination_customer_reference_idCustomer reference id for destination is invalid. Pass the customer reference id for the person or business associated with the destination external account.
400duplicate_transfer_reference_idResource already exists with the transfer reference id. Pass a unique transfer reference id.
400missing_amountAmount is required. Expecting number greater than zero.
400invalid_amountAmount is invalid. Expecting number greater than zero.
400missing_currencyCurrency is required. Must be “USD”.
400invalid_currencyCurrency is invalid. Must be “USD”.
400missing_speedSpeed is required. Expecting "standard", "same_day", or "asap".
400invalid_speedSpeed is invalid. Expecting "standard", "same_day", or "asap".
400invalid_account_statement_descriptorAccount statement descriptor is invalid.
400unknown_enterprise_external_accountEnterprise does not have associated external account in requested environment. Create an external account and pass your enterprise id in customer_reference_id.
400missing_transfer_group_idTransfer group is required.
400invalid_transfer_group_idTransfer group ID is invalid.
400invalid_source_account_reference_idAccount reference id source of the transfer does not match the transfer group
400invalid_source_customer_reference_idCustomer reference id source of the transfer does not match the transfer group
400invalid_destination_account_reference_idAccount reference id destination of the transfer does not match the transfer group
400invalid_destination_customer_reference_idCustomer reference id destination of the transfer does not match the transfer group

Transfer Groups Errors

HTTP status codeError codeError message
400missing_transfer_group_reference_idTransfer group reference id is required. Pass a unique transfer group reference id.
400missing_source_or_destinationSource or destination is required. Use source to specify that all transfers in this group ultimately come from the same source. Use destination to specify that all transfers in this group ultimately go to the same destination.
400invalid_source_and_destinationTransfer group is invalid. You cannot specify both an ultimate source and an ultimate destination in the same group.
400missing_source_account_reference_idAccount reference id for source is required. Pass the account reference id for the source external account.
400missing_source_customer_reference_idCustomer reference id for destination is required. Pass the customer reference id for the person or business associated with the destination external account.
400invalid_source_account_reference_idAccount reference id for source is invalid. Pass the account reference id for the source external account.
400missing_destination_account_reference_idAccount reference id for destination is required. Pass the account reference id for the destination external account.
400missing_destination_customer_reference_idCustomer reference id for destination is required. Pass the customer reference id for the person or business associated with the destination external account.
400invalid_destination_account_reference_idAccount reference id for destination is invalid. Pass the account reference id for the destination external account.
404unknown_idId is unknown. Pass the Orum-generated id for the transfer group in the id path parameter.