For push (third-party initiated) or pull (merchant initiated) requests, the response's HTTP headers will tell you what happened in the request.

❗️
An 'Error' in this context does not refer to an 'HTTP error' (e.g. response codes 400-499 or 500-599).
'Errors' here refer to when tokenization or detokenization was not executed properly. For example, x-cc-error (missing header) may be returned along with a HTTP response code of 200.

HTTP Header	Description
`x-cc-error-code`	An error code returned by PCI Proxy in case of error. This means we were not able to tokenize or detokenize properly.
`x-cc-error`	An error message returned by PCI Proxy which corresponds to `x-cc-error-code`. See the error table for more details.
`x-cc-matches`	Returned by us in case of success. The value represents the number of total replacements (card to alias or alias to card) that were made.
`x-cc-matches-ca`	The number of card to alias replacements.
`x-cc-matches-ac`	The number of alias to card replacements.
`x-cvv-matches`	The total number of CVV to alias and alias to CVV replacements.
`x-cvv-matches-acvv`	The number of alias to CVV replacements.
`x-cvv-matches-cvva`	The number of CVV to alias replacements.
`x-custom-matches`	Returned by us in case of a successful replacement. The value represents the number of total replacements (custom value to alias or alias to custom value) that were made.
`pci-proxy-masked-aliases`	This header contains pairs of tokens, in the format of `alias2.0=masked card`. For example, `AAABcH0Bq92s3kgAESIAAbGj5NIsAHWC=424242xxxxxx4242`. There is a pair for each tokenization and in the case of multiple tokens, they are separated by semicolons, for example: `AAABcH0BrGOs3kgAESIAAc6gFVXTAGTv=540400xxxxxx0001; AAABcH0Bq92s3kgAESIAAbGj5NIsAHWC=424242xxxxxx4242`
`x-cc-proxy-action-id`	The unique request identifier.

For push requests, the following header is also returned:

HTTP Header	Description
`x-cc-forwarded-for`	Returns the IP address of the origin called of the Push integration.

Special error cases

❗️
In case of XML requests/response bodies, the charset must be specified in the Content-type header so that we are able to read them properly.
If not specified, PCI Proxy defaults to ISO-8859-1.

If we are able to parse and correctly match the replacement targets but an error occurs during tokenization or detokenization, the match will be replaced with a constant which has 16 characters.

Possible constants	x-cc-error	Description
`0000000000000000`	Invalid card number.	The card number/CVV was matched but it was invalid.
`0000000000000001`	Internal error.	The card number/CVV was matched but an internal error occurred during the transformation to alias.

Example

If a channel response contains three card numbers and one of them fails to validate or convert, the two successful replacement tokens will be present in the returned body and the failed card number will be replaced with one of the two special constants above. No x-cc-error or x-cc-error-code headers will be returned and x-cc-matches will have the value 2.

Error codes

To reiterate, the following error codes are internal to PCI Proxy and are not related to HTTPS codes. They correspond to x-cc-error and x-cc-error-code as seen above.

Request errors

Error code	Error message	Explanation
`1`	Missing header: `<HEADER-NAME>`.	One or more required headers are missing.
`2`	Invalid `merchantId`.	Merchant not found, disabled or not properly configured. Get in touch with support.
`3`	Target host not allowed: `x-cc-url`.	The target URL is not allowed.
`4`	Invalid merchant setup: security sign was not defined.	Merchant did not define the security sign.
`5`	Invalid authentication (API-key or sign).	Either `pci-proxy-api-key` or `sign` is incorrect.
`6`	Invalid proxy type.
`7`	Invalid XPath.
`8`	Invalid target URL.
`9`	Invalid proxy type: white-label not matched.	The provided merchant/url headers did not match to a valid known proxy type. Get in touch with support.

Push request errors

Error code	Error message	Explanation
`50`	Missing parameter: `<PARAMETER-NAME>`.	Push request parameter missing.

HTTP layer errors

Error code	Error message	Explanation
`100`	Unsupported method: `<METHOD-NAME>`.	Unsupported HTTP method.

Processing errors

Error code	Error message	Explanation
`200`	Could not apply XPath on XML response: `<XPATH-EXPRESSION>`.	There was an error applying the XPATH expression.
`201`	Denied by velocity check.	Sent during alias to card conversion if there were too many attempts to convert bad aliases to cards. You can make 20 bad alias requests in a 15 minute window, after which the IP is blocked. As soon as you stop sending bad aliases, it takes a maximum of 15 minutes to get unblocked.
`202`	Denied by parallel connection checker.	Security measure for too many parallel requests.
`203`	Denied by whitelist.	The IP is not whitelisted on PCI Proxy. Get in touch with support.

Parse errors

Error code	Error message	Explanation
`300`	Unknown content type in third-party response: `<CONTENT-TYPE>`.	PCI Proxy is not able to parse the third-party response.
`301`	Unknown content type in source request: `<CONTENT-TYPE>`.	PCI Proxy is not able to parse the source request.
`303`	Invalid payload.

Configuration errors

Error code	Error message	Explanation
`400`	Pull not configured.	There is no pull configuration for the specified merchant. Get in touch with support.
`401`	Missing push configuration for: `<REASON>`.	Incorrect merchant configuration. Get in touch with support.
`402`	Missing billing configuration for: `<REASON>`.
`403`	Invalid SSL certificate.

Connection errors

Error code	Error message	Explanation
`800`	Connection error.	PCI Proxy could not connect to a third-party, or encountered an error that caused no response, for example a read timeout or DNS error. We return a HTTP error code of 504 (Gateway Timeout) and an empty response.

Unknown errors or exceptions

Error code	Error message	Explanation
`900`	PCI Proxy error.	Uncategorized system error.
`901`	PCI Proxy internal error.	Uncategorized internal system error.