Error Types

Error types that may be returned from the Omise API. See Errors for information about the structure.

Type Error Code HTTP Status
Charge brand_not_supported 400
Charge expired_charge 400
Charge failed_capture 400
Charge failed_multi_currency 400
Charge failed_refund 400
Charge failed_reverse 400
Charge failed_void 400
Charge invalid_amount 400
Charge invalid_charge 400
Charge processed_charge 400
Dispute invalid_dispute 400
Document documents_locked 400
Document invalid_file_type 400
Document missing_file 400
General authentication_failure 401
General backend_error 502
General bad_request 400
General failed_deletion 422
General feature_not_supported 400
General internal_error 500
General invalid_card_token 400
General key_expired_error 403
General locked_account_error 403
General not_found 404
General service_not_found 404
General used_token 400
Link invalid_link 400
Recipient invalid_bank_account 400
Recipient invalid_recipient 400
Search invalid_filter 422
Search invalid_page 422
Search invalid_per_page 422
Search invalid_scope 422
Search search_unavailable 503
Token invalid_card 400
Token invalid_domain 400
Token missing_card 400
Transfer invalid_transfer 400

Charge Errors

Brand Not Supported

An attempt was made to create a charge using a card with a brand not supported by the account.

Type Error Code HTTP Status
Charge brand_not_supported 400

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#brand-not-supported', 
 'code': 'brand_not_supported', 
 'message': 'brand not supported'
}

Expired Charge

An attempt was made to capture a charge, but the charge can no longer be captured. An authorized charge left uncaptured for more than 7 days (the exact duration depends on card issuing bank) will automatically be canceled.

Type Error Code HTTP Status
Charge expired_charge 400

Curl

curl https://api.omise.co/charges/chrg_test_4xvqmz1wx93it4cut8g/capture \
-X POST  \
-u skey_test_4xc6eevsmz5phbtjcaf:

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#expired-charge', 
 'code': 'expired_charge', 
 'message': 'charge expired'
}

Failed Capture

An attempt was made to capture a charge, but the charge was not captured. The charge might not be authorized yet, or it might have already been captured. The specific reason can be found in the message attribute.

Type Error Code HTTP Status
Charge failed_capture 400

Curl

curl https://api.omise.co/charges/chrg_test_4xvqmz1wx93it4cut8g/capture \
-X POST  \
-u skey_test_4xc6eevsmz5phbtjcaf:

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#failed-capture', 
 'code': 'failed_capture', 
 'message': 'capture failed'
}

Failed Multi Currency

The account multi-currency settings need to be adjusted. Please contact support@omise.co.

Type Error Code HTTP Status
Charge failed_multi_currency 400

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#failed-multi-currency', 
 'code': 'failed_multi_currency', 
 'message': 'the currency conversion could not be completed'
}

Failed Refund

An attempt was made to process a refund outside of the allowable, country-specific limits.

Type Error Code HTTP Status
Charge failed_refund 400

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#failed-refund', 
 'code': 'failed_refund', 
 'message': 'charge exceeds refund limit (1000 refunds/charge)'
}

Failed Reverse

An attempt was made to reverse a charge, but the charge was not reversed. See the message attribute for more information.

Type Error Code HTTP Status
Charge failed_reverse 400

Curl

curl https://api.omise.co/charges/chrg_test_4xso2s8ivdej29pqnhz/reverse \
-X POST \
-u skey_test_4xsjvwfnvb2g0l81sjz:

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#failed-reverse', 
 'code': 'failed_reverse', 
 'message': 'only uncaptured authorized charges can be reversed'
}

Failed Void

An attempt was made to void (e.g. refund) a charge, but the charge was not voided.

Type Error Code HTTP Status
Charge failed_void 400

Curl

curl https://api.omise.co/charges/chrg_test_4ype2jynk2len88i4er/refunds \
-X POST \
-u skey_test_4ypcvnwzy9ob6gs89pn: \
-d "amount=10000" \
-d "void=true"

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#failed-void', 
 'code': 'failed_void', 
 'message': 'void failed'
}

Invalid Amount

An attempt was made to create a charge with a non-integer amount.

Type Error Code HTTP Status
Charge invalid_amount 400

Curl

curl https://api.omise.co/charges \
-X POST \
-u skey_test_4xsjvwfnvb2g0l81sjz: \
-d "description=Invalid amount order" \
-d "amount[]=2000" \
-d "currency=thb" \
-d "return_uri=http://www.example.com/orders/3947/complete" \
-d "card=tokn_test_4xvpea0ifwajbx3f873"

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#invalid-amount', 
 'code': 'invalid_amount', 
 'message': 'invalid amount'
}

Invalid Charge

An attempt was made to create a charge that does not meet the minimum requirements. See the message attribute for more information.

Type Error Code HTTP Status
Charge invalid_charge 400

Curl

curl https://api.omise.co/charges \
-X POST \
-u skey_test_4xc6eevsmz5phbtjcaf: \
-d "amount=eleventy" \            # Not an integer
-d "currency=bottle caps" \       # Currently not an accepted currency
-d "return_uri=http://www.example.com/orders/3947/complete" \
-d "customer=cust_test_4xko29qxltncwq3u0i3"

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#invalid-charge', 
 'code': 'invalid_charge', 
 'message': 'currency is currently not supported and amount is not a number'
}

Processed Charge

An attempt was made to process an offline charge, but the charge was already processed.

Type Error Code HTTP Status
Charge processed_charge 400

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#processed-charge', 
 'code': 'processed_charge', 
 'message': 'charge was already processed'
}

Dispute Errors

Invalid Dispute

An attempt was made to modify a dispute outside of the allowed parameters.

Type Error Code HTTP Status
Dispute invalid_dispute 400

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#invalid-dispute', 
 'code': 'invalid_dispute', 
 'message': 'invalid dispute'
}

Document Errors

Documents Locked

An attempt was made to upload a file to a dispute that is no longer open (status=open).

Type Error Code HTTP Status
Document documents_locked 400

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#documents-locked', 
 'code': 'documents_locked', 
 'message': 'documents list cannot be modified'
}

Invalid File Type

An attempt was made to upload a file with a type outside of the allowed file types. See Documents API for supported filetypes.

Type Error Code HTTP Status
Document invalid_file_type 400

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#invalid-file-type', 
 'code': 'invalid_file_type', 
 'message': 'invalid content-type'
}

Missing File

An attempt was made to upload a non-existent file.

Type Error Code HTTP Status
Document missing_file 400

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#missing-file', 
 'code': 'missing_file', 
 'message': 'missing file or filename'
}

General Errors

Authentication Failure

An attempt was made to access the API using an invalid key. Check whether the API method accepts a private or public key. Current keys can be found in the account dashboard.

Type Error Code HTTP Status
General authentication_failure 401

Curl

curl https://api.omise.co/customers/cust_test_4xvqerqazpdhf5xu2zj \
-u skey_test_please_let_me_in:      # Incorrect secret key

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#authentication-failure', 
 'code': 'authentication_failure', 
 'message': 'authentication failed'
}

Backend Error

An error occurred communicating with the provider for this particular payment method. Please try again.

Type Error Code HTTP Status
General backend_error 502

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#backend-error', 
 'code': 'backend_error', 
 'message': 'backend error'
}

Bad Request

Several types of invalid requests return bad_request. See the message attribute for more information.

Type Error Code HTTP Status
General bad_request 400

Curl

curl https://api.omise.co/sources \
-X POST  \
-u skey_test_4xc6eevsmz5phbtjcaf:  \
-d "amount=10000" \
-d "currency=thb"  \
-d "type=invalid_type"  # Invalid type

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#bad-request', 
 'code': 'bad_request', 
 'message': 'bad request'
}

Failed Deletion

An attempt was made to delete an object (e.g. a link or a schedule), but the operation failed. See the message attribute for more information.

Type Error Code HTTP Status
General failed_deletion 422

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#failed-deletion', 
 'code': 'failed_deletion', 
 'message': 'this object could not be deleted'
}

Feature Not Supported

The requested feature is not currently enabled. Please contact support@omise.co.

Type Error Code HTTP Status
General feature_not_supported 400

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#feature-not-supported', 
 'code': 'feature_not_supported', 
 'message': 'Platform fee is not currently enabled for this account'
}

Internal Error

An internal server error occurred. If the error occurs again, please contact support@omise.co.

Type Error Code HTTP Status
General internal_error 500

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#internal-error', 
 'code': 'internal_error', 
 'message': 'request could not be completed due to an internal error'
}

Invalid Card Token

A attempt was made to perform an action which requires a card token string (e.g. tokn_test_4xvpea0ifwajbx3f873) using a non-string object (for example, a card dictionary) instead.

Type Error Code HTTP Status
General invalid_card_token 400

Curl

curl https://api.omise.co/customers \
-X POST \
-u skey_test_4xc6eevsmz5phbtjcaf: \
-d "description=John Doe (id: 30)" \
-d "email=john.doe@example.com" \
-d "card[number]=4242424242424242" \ # This endpoint expects a token, not a card object
-d "card[name]=Somchai Prasert"

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#invalid-card-token', 
 'code': 'invalid_card_token', 
 'message': 'invalid card token'
}

Key Expired Error

An attempt was made to perform a request using an expired (i.e. revoked) key. Current keys can be found in the account dashboard.

Type Error Code HTTP Status
General key_expired_error 403

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#key-expired-error', 
 'code': 'key_expired_error', 
 'message': 'expired key'
}

Locked Account Error

The account is locked. Please contact support@omise.co.

Type Error Code HTTP Status
General locked_account_error 403

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#locked-account-error', 
 'code': 'locked_account_error', 
 'message': 'account locked'
}

Not Found

An attempt was made made to reference an object ID (e.g. rfnd_test_5dvfvd32uiabudlr3v7) that could not be found. Check that the request is correct, and that it is being performed on the correct account.

Type Error Code HTTP Status
General not_found 404

Curl

curl https://api.omise.co/customers/cust_test_000000000000 \ # Not a valid customer ID.
-u skey_test_4xc6eevsmz5phbtjcaf:

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#not-found', 
 'code': 'not_found', 
 'message': 'the requested object was not found'
}

Service Not Found

An attempt was made to use a feature which is not supported by the API version of the request. If the API version is not specified in the header of the request (e.g. Omise-Version=2017-11-02), the API version of the account is used by default. Learn how to update API versions here.

Type Error Code HTTP Status
General service_not_found 404

Curl

curl https://api.omise.co/sources \
-X POST \
-u skey_test_54f501mmzcl8bukll65: \
-d "amount=10025" \
-d "currency=thb" \
-d "type=bill_payment_tesco_lotus"

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#service-not-found', 
 'code': 'service_not_found', 
 'message': 'you are using api version which does not support this operation'
}

Used Token

An attempt was made to re-use a token. Tokens are single use only.

Type Error Code HTTP Status
General used_token 400

Curl

curl https://api.omise.co/customers \
-X POST \
-u skey_test_4xc6eevsmz5phbtjcaf: \
-d "description=John Doe (id: 30)" \
-d "email=john.doe@example.com" \
-d "card=tokn_test_4xvpea0ifwajbx3f873" # This token has already been used

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#used-token', 
 'code': 'used_token', 
 'message': 'token was already used'
}

Link Errors

An attempt was made to create a link with an invalid currency or with no description parameter.

Type Error Code HTTP Status
Link invalid_link 400

Curl

curl https://api.omise.co/links \
-X POST \
-u skey_test_4xsjvwfnvb2g0l81sjz: \
-d "description=Invalid currency input" \
-d "amount=2000" \
-d "currency=aaa"

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#invalid-link', 
 'code': 'invalid_link', 
 'message': 'invalid link'
}

Recipient Errors

Invalid Bank Account

An attempt was made to create a recipient with an invalid bank account. See Supported Banks.

Type Error Code HTTP Status
Recipient invalid_bank_account 400

Curl

curl https://api.omise.co/recipients \
-X POST \
-u skey_test_4xsjvwfnvb2g0l81sjz: \
-d "name=James Smith" \
-d "email=test_recp123@localhost" \
-d "description=My first other recipient" \
-d "type=individual" \
-d "tax_id=1234567890" \
-d "bank_account[brand]=invalid-bank" \
-d "bank_account[number]=acc12345" \
-d "bank_account[name]=James Smith"

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#invalid-bank-account', 
 'code': 'invalid_bank_account', 
 'message': 'invalid bank account'
}

Invalid Recipient

An attempt was made to update a recipient in an invalid way (e.g. deleting a recipient that cannot be deleted).

Type Error Code HTTP Status
Recipient invalid_recipient 400

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#invalid-recipient', 
 'code': 'invalid_recipient', 
 'message': 'invalid recipient'
}

Search Errors

Invalid Filter

An invalid key was passed to the search filters parameter. Search requests expect specific set of filter keys. See list of available filters.

Type Error Code HTTP Status
Search invalid_filter 422

Curl

curl 'https://api.omise.co/search?scope=charge&filters[currency]=thb' \
-X GET \
-u skey_test_4xc6eevsmz5phbtjcaf:

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#invalid-filter', 
 'code': 'invalid_filter', 
 'message': 'invalid filters'
}

Invalid Page

An invalid number was passed to the search page parameter. Search requests expect positive integers in the page parameter.

Type Error Code HTTP Status
Search invalid_page 422

Curl

curl 'https://api.omise.co/search?scope=charge&filters[captured]=true&page=0' \
-X GET \
-u skey_test_4xc6eevsmz5phbtjcaf:

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#invalid-page', 
 'code': 'invalid_page', 
 'message': 'invalid page'
}

Invalid Per Page

An invalid number was passed to the search per_page parameter. Search requests expect positive integers in the per_page parameter.

Type Error Code HTTP Status
Search invalid_per_page 422

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#invalid-per-page', 
 'code': 'invalid_per_page', 
 'message': 'invalid per page'
}

Invalid Scope

An invalid (or missing) string was passed to the search scope parameter. Search requests expect a scope to be one a predefined list of scopes. See list of available scopes.

Type Error Code HTTP Status
Search invalid_scope 422

Curl

curl 'https://api.omise.co/search?scope=accounts' \
-X GET \
-u skey_test_4xc6eevsmz5phbtjcaf:

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#invalid-scope', 
 'code': 'invalid_scope', 
 'message': 'invalid scope'
}

Search Unavailable

Search is temporarily unavailable. Please try again.

Type Error Code HTTP Status
Search search_unavailable 503

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#search-unavailable', 
 'code': 'search_unavailable', 
 'message': 'search is temporarily unavailable'
}

Token Errors

Invalid Card

An attempt was made to create a token with invalid parameters.

Type Error Code HTTP Status
Token invalid_card 400

Curl

curl https://vault.omise.co/tokens \
-X POST \
-u pkey_test_4xc6eevsm4i0ysitb4j: \
-d "card[name]=JOHN DOE" \
-d "card[city]=Bangkok" \
-d "card[number]=Definitely not a card number" \ # Invalid card number!
-d "card[expiration_month]=10" \
-d "card[expiration_year]=2016"

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#invalid-card', 
 'code': 'invalid_card', 
 'message': 'invalid card'
}

Invalid Domain

An attempt was made to generate a token using the api.omise.co domain. Use vault.omise.co to generate tokens.

Type Error Code HTTP Status
Token invalid_domain 400

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#invalid-domain', 
 'code': 'invalid_domain', 
 'message': 'request must be made with the vault.omise.co domain'
}

Missing Card

An attempt was made to create a token with invalid card parameters.

Type Error Code HTTP Status
Token missing_card 400

Curl

curl https://vault.omise.co/tokens \
-X POST \
-u pkey_test_4xc6eevsm4i0ysitb4j:
# Omitting the following parameters:
#-d "card[name]=JOHN DOE" \
#-d "card[city]=Bangkok" \
#-d "card[postal_code]=10320" \
#-d "card[number]=4242424242424242" \
#-d "card[expiration_month]=10" \
#-d "card[expiration_year]=2016"

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#missing-card', 
 'code': 'missing_card', 
 'message': 'request contains no card parameters'
}

Transfer Errors

Invalid Transfer

An attempt was made to update a transfer in an invalid way (e.g. deleting a transfer that cannot be deleted or transferring more than the available balance.)

Type Error Code HTTP Status
Transfer invalid_transfer 400

JSON Response

{
 'object': 'error', 
 'location': 'https://www.omise.co/api-errors#invalid-transfer', 
 'code': 'invalid_transfer', 
 'message': 'this transfer has already been sent and cannot be destroyed anymore'
}