Errors

In this section, you’ll find an example of a standardized error response format used for troubleshooting integration issues. Each error response is structured to help identify, track, and resolve specific issues quickly. Use these details to diagnose and correct issues efficiently. Here’s what the fields represent.

Error Message Fields

Field	Description
errorMessage	Provides a clear description of the error encountered, often including the field and value causing the issue.
responseIdentifier	A unique identifier for the response, useful for tracking and referencing specific requests in support inquiries.
errorCode	A numeric code categorizing the error type for streamlined troubleshooting.

Example Error Response

This example demonstrates a possible error when an invalid currency value is supplied.

{
  "errorMessage": "Field [Currency] contains an unknown value. Value: [eur].",
  "responseIdentifier": "e3605f81-6b09-4ce1-83ad-5a8d49f3cd44",
  "errorCode": "2003"
}

Error Codes

This section provides a comprehensive table of both parse and validation error codes for reference during integration. Each code is accompanied by a description of the error and an example, where applicable, to illustrate common issues that may arise. These error codes are intended to guide developers in quickly identifying and resolving related issues by highlighting specific fields, expected values, and conditions.

• Code: Unique identifier for each error type.
• Error Message: Detailed message describing the validation issue, often containing the field and value involved.
• Example: Example messages that illustrate how each error may appear in actual usage.

This table will assist you in understanding and addressing validation requirements effectively, ensuring smooth integration and accurate data handling.

Parse Error Codes

These error codes will appear when something is wrong with your request body.

Code	Error Message	Example
1000	The provided request body was an invalid JSON.	-
1001	The provided request body needs to start with '{'.	-
1002	The provided request body does not end properly. Missing '}'.	-
1003	An array in the provided request body does not end properly. Missing ']'.	-
1004	An object in the provided request body does not end properly. Missing '}'.	-
1005	Could not parse field [{0}]. Expected a {1}.	Could not parse field [Amount]. Expected a Number.
1006	Unknown field [{0}] in the JSON request body.	Unknown field [TarzansMaidenName] in the JSON request body.

Validation Error Codes

These error codes will appear when parsing your request.

Code	Error Message	Example
2000	Field [{0}] cannot be empty.	Field [Amount] cannot be empty.
2001	Field [{0}] is not a valid number. Value: [{1}].	Field [Amount] is not a valid number. Value: [12.69].
2002	Field [{0}] must be greater than 0. Value: [{1}].	Field [Amount] must be greater than 0. Value: [-1].
2003	Field [{0}] contains an unknown value. Value: [{1}].	Field [Currency] contains an unknown value. Value: [eur].
2004	Field [{0}] cannot be resolved. Value: [{1}].	Field [ReturnUrl] cannot be resolved.
2005	Field [{0}] cannot be in the past. Value: [{1}].	Field [ExpiresAt] cannot be in the past. Value: [2020-05-05T11:00:00.000Z].
2006	Field [{0}] cannot be more than {1} hours in the future. Value: [{2}].	Field [ExpiresAt] cannot be more than 24 hours in the future. Value: [2040-05-05T11:00:00.000Z].
2007	Sum of [{0}] (Value: {1}) must be equal to [{2}] (Value: {3}).	Sum of [Items] (Value: 200) must be equal to [Amount] (Value: 123).
2008	Field [{0}] contains an unsupported value. Value: [{1}]. Supported values: [{2}].	Field [Currency] contains an unsupported value. Value: [BAM]. Supported values: [ISK, EUR, USD, GBP, CAD, DKK, NOK, SEK].
2009	Field [{0}] exceeds maximum length of [{1}]. Value: [{2}].	Field [Reference] exceeds maximum length of [100]. Value: [aaaa....aaaa].
2010	Merchant cannot access the theme or the theme does not exist. Value: [{0}].	Merchant cannot access the theme or the theme does not exist. Value: [17].
2011	Merchant does not have a contract in the currency the request was created. Value: [{0}].	Merchant does not have a contract in the currency the request was created. Value: [EUR].
2012	Field [{0}] does not meet the minimum length requirement of [{1}]. Value: [{2}].	Field [MerchantShopperReference] does not meet the minimum length requirement of [3]. Value: [T].
2013	Fields provided are not intended to be used together. Fields: [{0}].	Fields provided are not intended to be used together. Fields: [IsManualCapture, CaptureHoursDelay].
2014	Merchant cannot access entity or the entity does not exist. Value: [{0}].	-
2015	Authorization currency and capture currency do not match. Value: [{0}].	-
2016	Merchant cannot access terminal or terminal does not exist. Value: [{0}].	-
2017	Field [{0}] must be exactly [{1}] characters long. Value: [{2}].	-
2018	A request with the same reference was already processed.	-
2019	Amount requested is too high. Value: [{0}]	-
2020	Request could not be processed. Please contact support.	-
2021	One payment method must be provided.	-
2022	Amount requested is lower than the minimum amount for the currency. Value: [{0}]. Min amount: [{1}].	Amount requested is lower than the minimum amount for the currency. Value: [100]. Min amount: [200].
2023	Amount requested is invalid for tokenization. Amount must be either 0 or the minimum amount for the currency. Value: [{0}]. Min amount: [{1}]	Amount requested is invalid for tokenization. Amount must be either 0 or the minimum amount for the currency. Value: [100]. Min amount: [200]
2024	Origin is not in the allowed origins for the terminal identifier. Value: [{0}]. Allowed origins: [{1}]	Origin is not in the allowed origins for the terminal identifier. Value: [https://fake.com]. Allowed origins: [https://real.com, https://test.com]
2025	Item amount cannot be greater than amount without discount. Amount: [{0}]. Without Discount: [{1}].	Item amount cannot be greater than amount without discount. Amount: 100. Without Discount: 50.
2026	Amount in minor units for ISK must end in 00. Value: [{0}].	Amount in minor units for ISK must end in 00. Value: [489].
2027	Origins are not set up for the terminal identifier.	-
2028	Field [{0}] available only in test environment.	Field [requestedTestAcquirerResponseCode] available only in test environment.
2029	Number of items cannot exceed [{0}].	Number of items cannot exceed [200].
2030	Items are not allowed in this type of payment link. Type: [0].	Items are not allowed in this type of payment link. Type: [TokenizeByLink].
2031	Shopper info for the same field already exists. Field: [0].	Shopper info for the same field already exists. Field: [Ssn].
2032	Recurring processing model is not allowed in this type of payment link. Type: [0].	Recurring processing model is not allowed in this type of payment link. Type: [PayByLink].
2033	Amount requested is invalid for this type of payment link. Type: [0].	Amount requested is invalid for this type of payment link. Type: [TokenizeByLink].
2034	Cannot provide prefilled value unless the requirement type is set to prefill. Field: [0].	Cannot provide prefilled value unless the requirement type is set to prefill. Field: [ShopperInfos[0].PrefilledValue].
2035	Payment link is already disabled. Reference: [0].	Payment link is already disabled. Reference: [aaaaaaaaaaaaaa].
2036	[{0}] cannot be less then 0 or greater than 100.	[PageSize] cannot be less then 0 or greater than 100.
2037	Request must contain both MerchantShopperReference and RecurringProcessingModel.	-
2038	Unable to process request due to PCI DSS compliance status.	-
2039	Unable to process due to merchant status - Inactive. Please contact support.	-

Troubleshooting Errors

This section covers common errors reported by integrators, with more context than the table above provides. It will grow over time as we identify more common issues. Several of these relate to the terminalIdentifier, origin, threeDsReturnUrl, and returnUrl fields — see Terminal Identifier for background on terminals themselves.

2004 - Field cannot be resolved

{
  "errorMessage": "Field [Origin] cannot be resolved. Value: [-].",
  "responseIdentifier": "e3605f81-6b09-4ce1-83ad-5a8d49f3cd44",
  "errorCode": "2004"
}

{
  "errorMessage": "Field [ThreeDsReturnUrl] cannot be resolved. Value: [localhost:4202/payment?checkoutId=0uli0ytwpchd&success=yes].",
  "responseIdentifier": "e3605f81-6b09-4ce1-83ad-5a8d49f3cd44",
  "errorCode": "2004"
}

For URL fields (origin, threeDsReturnUrl, returnUrl, abandonUrl), this means the value sent is not a valid, absolute URL. To be accepted, the value must:

• Start with http:// or https://. A bare host/path such as localhost:4202/payment?... is rejected because it has no scheme — send http://localhost:4202/payment?... instead.
• Be a real value, not a placeholder. A value of - (or an empty string) means the field wasn't actually populated with a URL before the request was sent.

2016 - Merchant cannot access terminal or terminal does not exist

{
  "errorMessage": "Merchant cannot access terminal or terminal does not exist. Value: [1adfe4a1b2c3]",
  "responseIdentifier": "e3605f81-6b09-4ce1-83ad-5a8d49f3cd44",
  "errorCode": "2016"
}

The terminalIdentifier value doesn't match a terminal your API key can access. Common causes:

• The identifier was copied from the wrong terminal — each solution (Hosted Checkout, Payment Gateway, Payment Links, ...) has its own Terminal Identifier, so reusing one from a different solution will fail.
• The identifier belongs to the wrong environment — a test/staging identifier doesn't work against the live API, and vice versa.
• The identifier has a typo, extra whitespace, or was truncated when it was copied.

Re-copy the value from the Merchant Portal for the specific terminal and environment you're calling — see Terminal Identifier.

2024 - Origin is not in the allowed origins for the terminal identifier

{
  "errorMessage": "Origin is not in the allowed origins for the terminal identifier. Value: [http://localhost:4202/]. Allowed origins: [http://localhost:4200, https://localhost:4200, https://hey-iceland-git-dev-baendaferdir.vercel.app]",
  "responseIdentifier": "e3605f81-6b09-4ce1-83ad-5a8d49f3cd44",
  "errorCode": "2024"
}

The origin you send is compared by scheme, host, and port against the Allowed Origins configured for that terminal — the path, query string, and trailing slash are ignored, so http://localhost:4202/ and http://localhost:4202 are treated the same.

In the example above, the request came from port 4202, but only port 4200 is allowed for that terminal — even a one-character difference in port, scheme, or host is enough to fail the check. Other common causes:

• http:// used where only https:// is allowed, or vice versa.
• A new environment — a new local port, a preview deployment, a new domain — that hasn't been added yet.

To fix it, open the Merchant Portal, go to Terminals > select the terminal > Allowed Origins, and add the exact origin your application runs from for every environment you use (local development, staging, production). Wildcards are supported for subdomains, e.g. https://*.example.com, if you need to allow multiple preview or subdomain deployments at once.

2027 - Origins are not set up for the terminal identifier

{
  "errorMessage": "Origins are not set up for the terminal identifier.",
  "responseIdentifier": "e3605f81-6b09-4ce1-83ad-5a8d49f3cd44",
  "errorCode": "2027"
}

This terminal has no Allowed Origins configured at all, so every request from a browser (channel: Web) fails this check until at least one is added.

To fix it, open the Merchant Portal, go to Terminals > select the terminal > Allowed Origins, and add the origin(s) your application will call from.

info

Allowed Origins only apply to Payment Gateway terminals and the Web channel — they aren't used for Hosted Checkout, Payment Links, or the Android/iOS channels.