> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pcibooking.net/llms.txt
> Use this file to discover all available pages before exploring further.
# Error Handling
> Every PCI Booking error condition with its exact response text, why it happens, and how to resolve it. Grouped by the part of the API that raises it.
Every failed API call returns the same three-part shape: a numeric `code`, a fixed `message` for that code, and a `moreInfo` string describing the specific failure. This page lists the conditions you are most likely to hit, with the exact text each returns and what to do about it.
## How to read an error
The `code` alone is rarely enough to identify a problem. Several codes are deliberately broad: `-125` covers every kind of bad input, and `-1003` covers everything from a wrong API key to a deleted token. Three pieces of information together identify a condition:
Narrows the class of failure, and maps to the HTTP status. See the table below.
Names the specific failure. This is the most useful field and the one to search for on this page. Some conditions leave it empty, which is itself a clue.
The same code and message mean different things on different endpoints. `-1003` on an authentication call is a credential problem; on a token call it usually is not.
Errors are returned in the same format as the request. Send JSON and the error comes back as a JSON object; send XML and it comes back as an `ErrorBlock` element. Parse both `code` and `moreInfo` - handling only the HTTP status loses the detail that identifies the cause.
## Codes and their fixed text
The `message` for a given code never varies. Only `moreInfo` changes.
| Code | `message` | HTTP |
| ------- | -------------------------------------------------------------------------------- | ----- |
| `-112` | Destination is bad | `400` |
| `-113` | This operation is not allowed for the given entity | `403` |
| `-123` | Message badly formatted | `400` |
| `-125` | Bad input data | `400` |
| `-126` | Request entity too large | `413` |
| `-150` | System error | `500` |
| `-160` | Uri not found | `404` |
| `-168` | Data integrity failed | `409` |
| `-175` | Request timed out | `504` |
| `-179` | Bad input parameter | `400` |
| `-1002` | Missing authentication header | `401` |
| `-1003` | You are not authorized to access this resource. Please contact customer support. | `401` |
| `-1010` | Resource is locked for updates | `423` |
| `0` | Application error: 0 | `500` |
A handful of codes exist in the platform but are never returned by this API - they belong to the portal's own sign-in flow. If you are building against the API you will not see `-174`, `-176`, `-180`, `-1004`, `-1005` or `-1006`.
## Authentication and access
**HTTP status:** `401`
**`message`:** `Missing authentication header`
**`moreInfo`:** one of the following, depending on which scheme the endpoint uses:
```text theme={null}
Missing or empty 'Authorization:' header
Badly formatted 'Authorization:' header
Missing 'APIKEY' keyword in the 'Authorization:' header
No accessToken query parameter value
No captureCardId query parameter value
```
**Reason.** The request carried no `Authorization` header at all. This is a missing header, not a rejected credential - a wrong or expired credential returns `-1003` instead.
**How to resolve.**
1. Add an `Authorization` header. For API key auth the value is your key prefixed with `APIKEY`, for example `APIKEY your-api-key`.
2. Check that your HTTP client is not stripping the header on redirect. A 301 or 302 between your client and the API drops `Authorization` in most clients.
**See also:** [Authentication](/getting-started/authentication)
**HTTP status:** `401`
**`message`:** `You are not authorized to access this resource. Please contact customer support.`
**`moreInfo`:**
```text theme={null}
Invalid API Key
Expiration time invalid: Already expired
Expiration time invalid: too late
```
The two expiration variants apply to one-time access tokens: the first means the token has passed its expiry, the second that the requested lifetime exceeded the maximum allowed and was refused outright rather than capped.
**Reason.** Authentication itself failed: the API key or session token was not recognised, has expired, or belongs to a different environment than the endpoint you called.
**How to resolve.**
1. Confirm the `APIKEY` prefix is present and there is a single space between it and the key.
2. Confirm the key belongs to the same environment as the host you called. Sandbox and production keys are not interchangeable.
3. If you are using a session token, check it has not passed its time to live and start a new session if it has.
**See also:** [Authentication](/getting-started/authentication)
**HTTP status:** `401`
**`message`:** `You are not authorized to access this resource. Please contact customer support.`
**`moreInfo`:** one of the following, depending on which check failed:
```text theme={null}
User is not the owner of this bank card
Merchant or Owner are not associated with bank card [] userID:
User is not associated with bank card []
```
**Reason.** The credential authenticated fine, but it is not allowed to act on the token in the request. The generic wording makes this the single most misread error in the API. On a token call it is far more often one of the causes below than an actual permissions problem.
**How to resolve.**
1. **Check the token was not deleted.** This is the most common cause. Deletion is permanent, and every later call on that token returns `-1003` rather than a not-found error. Support can confirm when and by which user a token was deleted.
2. **Check the tokenization actually succeeded.** If the call that should have created the token failed, the token never existed, and the first call that uses it reports `-1003`.
3. **Check the environment.** A sandbox token cannot be used from production, or the reverse.
4. **Check ownership and association.** See the rules below.
**Ownership and association.**
A token is owned by the account that created it. Another account can use the token only if the token was explicitly associated with it:
* **At tokenization**, by passing `merchantId` on the tokenizing call.
* **After tokenization**, by associating the token with the merchant.
Two rules catch people out:
* An association can only target a **primary** account. If you pass the ID of a sub-user or a secondary property, the request is rejected and you must associate the token with the parent account instead.
* Tokens never cross environments. A token created in sandbox cannot be used from production, and the reverse is also true.
**Account level blocks.**
An account that has exceeded its processing allowance is blocked, and every billable API call from it then fails with `-1003` even though the credentials are still valid and can still sign in to the portal. The response carries no `moreInfo` explaining this, so it is indistinguishable from a permissions failure by looking at the response alone.
This is a common cause on sandbox accounts, which have a lower allowance than production.
**Check for it when `-1003` appears suddenly across calls that used to work, on more than one token.** A block affects every billable call on the account at once, whereas a genuine ownership problem affects only the specific token. Contact [support](https://pcibooking.net/pci-booking-support/) with your account name to have the allowance reviewed and the block lifted.
**HTTP status:** `401`
**`message`:** `You are not authorized to access this resource. Please contact customer support.`
**`moreInfo`:**
```text theme={null}
Wrong sender id
```
**Reason.** The `SenderID` in the body does not match the account the API key authenticates as. The API will not let one account send a card request on behalf of another.
**How to resolve.**
1. Set `SenderID` to the user ID of the account whose API key you are using.
2. If you operate several accounts, check you have not paired one account's key with another account's `SenderID`.
## Tokens
**HTTP status:** `404`
**`message`:** `Uri not found`
**`moreInfo`:**
```text theme={null}
The provided card token does not exist or was already deleted
Token not found
```
**Reason.** The token is well formed but no card is stored against it. Either it never existed, or it was deleted. Deletion is permanent and cannot be undone.
**How to resolve.**
1. Confirm the tokenization call that should have created it returned success and returned this exact token.
2. Check whether the token was deleted, either explicitly or by a CVV retention policy configured to delete the card on cleanup.
3. Check the environment. A token from one environment is not visible in the other.
Some endpoints report a deleted token as `-1003` rather than `-160`. Treat the two as the same investigation and start with whether the token still exists.
**HTTP status:** `404`
**`message`:** `Uri not found`
**`moreInfo`:**
```text theme={null}
Invalid Card Uri value
Token value is not valid
```
**Reason.** The value could not be read as a token at all, so no lookup was attempted. The token part of the URI must be 32 hexadecimal characters.
**How to resolve.**
1. Pass the full token URI exactly as it was returned to you, for example `https://service.pcibooking.net/api/payments/paycard/<32-hex-token>`.
2. Check for truncation, URL encoding, or a trailing space introduced by your own storage or logging.
**HTTP status:** `404`
**`message`:** `Uri not found`
**`moreInfo`:**
```text theme={null}
Resource not matching request
Resource not matching request. Cannot update a paycard
Resource not matching request. Cannot retrieve a paycard
```
**Reason.** The token exists, but it does not hold the kind of record this endpoint works on. The usual case is calling a card operation against a token that holds payment information rather than a card, or calling a card entry operation against a token created by a different capture type.
**How to resolve.**
1. Check which endpoint created the token, and use the matching endpoint to read or update it.
2. For a card captured through a hosted form, use the retrieval endpoint for that capture type.
**HTTP status:** `400`
**`message`:** `Bad input data`
**`moreInfo`:**
```text theme={null}
Expiration year/month error
```
**Reason.** The expiration month or year is missing, out of range, or in a format the endpoint does not accept.
**How to resolve.**
1. Send the month as two digits, `01` through `12`.
2. Check the year format the endpoint expects. Some accept two digits and some four, and they are not interchangeable.
3. Check the date is not in the past. An expired card is rejected at tokenization.
**See also:** [Card Validation Errors](/reference/card-validation-errors)
**HTTP status:** `400`
**`message`:** `Bad input parameter`
**`moreInfo`:**
```text theme={null}
Invalid CVV value:
```
**Reason.** The CVV did not match the expected shape of three or four digits.
**How to resolve.**
1. Send digits only, with no spaces or punctuation.
2. Use four digits for American Express and three for other brands.
3. Omit the field entirely rather than sending an empty string when you have no CVV to send.
## Accounts and merchant association
**HTTP status:** `400`
**`message`:** `Bad input data`
**`moreInfo`:**
```text theme={null}
Could not find a valid merchant for
```
**Reason.** The `merchantId` you passed is not a merchant that your account can associate a token with. Either the ID does not exist, or it belongs to an account unrelated to yours.
**How to resolve.**
1. Check the `merchantId` value. For a property it is the external user ID, not the internal one.
2. Confirm the merchant sits under the same parent account as the credential making the call.
**HTTP status:** `403`
**`message`:** `This operation is not allowed for the given entity`
**`moreInfo`:**
```text theme={null}
Please associate the card to the primary property
Please associate the card to the primary booker -
```
**Reason.** A token can only be associated with a **primary** account. You passed the ID of a sub-user or a secondary property, which cannot own an association.
**How to resolve.**
1. Use the primary account's ID instead. When the message names an account ID, that is the one to use.
2. Sub-users of the primary account can then use the token without needing their own association.
## Token replacement and relay
**HTTP status:** `400`
**`message`:** `Bad input data`
**`moreInfo`:** the wording depends on which endpoint you called:
```text theme={null}
Couldn't fetch a valid screening profile::
Couldn't fetch a valid pciShield profile::
```
The first is returned by token replacement in a request (`paycard/relay`). The second is returned by tokenization on response (`paycard/capture`). They mean the same thing.
**Reason.** The `profileName` you passed could not be resolved for the account making the request. In almost every case the profile does exist, but on a different account than the one your credentials belong to. A misspelled profile name produces the same error.
**How to resolve.**
A PCI Shield profile belongs to the **account**, not to the sub-user that calls the API. When a sub-user makes a request, the profile is looked up against that sub-user's parent account. A profile configured on one account is never visible to a sub-user of a different account, and sandbox and production accounts are separate.
**To check which profiles your credential can see:**
1. Identify the parent account of the sub-user whose credentials you are using.
2. Sign in to the [PCI Booking portal](https://users.pcibooking.net) as that account and open **PCI Shield Settings** > **PCI Shield Profile Settings**.
3. Confirm the profile name appears there, spelled exactly as you send it. Profile names are matched exactly.
4. If the profile is listed under a different account, switch your request to a sub-user of that account rather than copying the profile.
There is no API endpoint that lists the profiles on your own account. `GET /api/booker` returns the platform-wide preset tokenization profiles, which are a different set. Your own profiles are visible in the portal only.
**See also:** [Content Filters](/account-setup/content-filters), [Target Profiles](/account-setup/target-profiles)
**HTTP status:** `400`
**`message`:** `Bad input data`
**`moreInfo`:**
```text theme={null}
Replacement of content failed
Could not apply token replacement onto content
```
**Reason.** The body parsed, but the profile's selectors did not match anything in it, so no card data was substituted. The request was not relayed. This is a mismatch between the profile and the payload, not a problem with the token.
**How to resolve.**
1. Compare the profile's selectors against the exact payload you sent. A selector that assumes a different nesting depth or element name matches nothing.
2. Check the namespaces. For XML and SOAP, a selector written without namespace handling will not match a namespaced document.
3. Confirm the body is the format the profile was written for. A profile written for XML will not match a JSON body.
4. Test the profile against a saved copy of a real request before using it in production.
**See also:** [Content Filters](/account-setup/content-filters)
**HTTP status:** `400`
**`message`:** `Bad input data`
**`moreInfo`:**
```text theme={null}
Content is empty
Content is missing/empty
Empty relay message content
```
**Reason.** Token replacement had nothing to work on. The body of the request you asked to be relayed was empty, so there was no content in which to substitute card data.
**How to resolve.**
1. Send the third-party request you want relayed as the body of the call, not as a query parameter.
2. If you are pointing at the content with a parameter name, check that parameter is present and actually carries the payload.
3. Check no proxy or client library between you and the API is dropping the body on a `GET` relay.
**HTTP status:** `400`
**`message`:** `Bad input data`
**`moreInfo`:**
```text theme={null}
Content type is missing/empty
```
**Reason.** Token replacement needs to know how to parse the body before it can find the placeholders. Without a `Content-Type` header it cannot choose a parser.
**How to resolve.**
1. Set `Content-Type` to match the body you are sending, for example `application/json`, `text/xml`, or `application/x-www-form-urlencoded`.
2. Send the charset if the third party requires one, for example `text/xml; charset=UTF-8`.
**HTTP status:** `400`
**`message`:** `Bad input data`
**`moreInfo`:**
```text theme={null}
httpMethod should be 'POST','GET','PUT','PATCH','DELETE'
```
**Reason.** The `httpMethod` parameter names a method the relay does not forward.
**How to resolve.**
1. Use one of `POST`, `GET`, `PUT`, `PATCH` or `DELETE`, in upper case.
2. Omit the parameter to accept the default of `POST`.
**HTTP status:** `400`
**`message`:** `Bad input data`
**`moreInfo`:**
```text theme={null}
Target Uri invalid
```
**Reason.** The `targetUri` could not be parsed as an absolute URL, so the relay had nowhere to send the request.
**How to resolve.**
1. Send an absolute URL including the scheme, for example `https://api.example.com/path`.
2. URL-encode the value if you pass it as a query parameter, so that its own query string does not terminate yours.
**HTTP status:** `400`
**`message`:** `Bad input data`
**`moreInfo`:**
```text theme={null}
Token(s) could not be found in custom header X-pciBooking-cardUri
```
**Reason.** The relay was told to take the token from the `X-pciBooking-cardUri` header, but the header was absent or held no readable token.
**How to resolve.**
1. Add the `X-pciBooking-cardUri` header carrying the full token URI.
2. Separate multiple tokens as the endpoint documents, and check none of them is empty.
**HTTP status:** `504`
**`message`:** `Request timed out`
**`moreInfo`:** not populated for this condition. The code and the endpoint are the only signal.
**Reason.** PCI Booking relayed your request but the target server did not answer within the timeout. The failure is on the far side, not in PCI Booking. Card data may already have reached the third party, so the operation cannot be assumed not to have happened.
**How to resolve.**
1. Raise the `timeout` parameter if the third party is legitimately slow. Check the maximum the endpoint accepts before relying on a high value.
2. Confirm the target host is reachable and not rate limiting or blocking the call. PCI Booking calls the third party from its own addresses, which the third party may need to allow.
3. **Do not blind retry a charge.** Query the third party for the outcome first. A timeout is an unknown result, not a failure.
**See also:** [Outbound IPs](/reference/outbound-ips)
## Request format
**HTTP status:** `400`
**`message`:** `Message badly formatted`
**`moreInfo`:**
```text theme={null}
Bad XML document
Bad XML document. Errors:
```
**Reason.** The endpoint expects XML that validates against its schema, and the body either did not parse as XML or failed validation. When validation is the cause, the failing details are listed in `moreInfo`.
**How to resolve.**
1. Read the list in `moreInfo`. It names the elements that failed, which is usually enough on its own.
2. Check element order. The schema is sequence-sensitive, so correctly named elements in the wrong order still fail.
3. Check the declared encoding matches what you actually sent.
**See also:** [Card Data XML Structure](/reference/card-data-xml-structure)
## Payment gateway
**HTTP status:** `400`
**`message`:** `Bad input data`
**`moreInfo`:**
```text theme={null}
Request object could not be parsed
```
**Reason.** The body could not be deserialised into the object the endpoint expects, so no field level validation ran. A single malformed field or a wrong container type is enough.
**How to resolve.**
1. Validate the body against the endpoint's schema before sending.
2. Check for a value sent as the wrong type, most often a number sent as a string or an object sent where an array is expected.
3. Check `Content-Type` matches the body format.
**HTTP status:** `400`
**`message`:** `Bad input data`
**`moreInfo`:**
```text theme={null}
Missing Card object
Missing CardToken property
Bad or Missing CardToken property
```
**Reason.** The transaction carried no card to charge. Either the card object is absent, or the `CardToken` property is missing or not a readable token URI.
**How to resolve.**
1. Send exactly one of a card object or a `CardToken`, as the endpoint requires.
2. Pass the full token URI, not the bare 32-hex token, unless the endpoint documents otherwise.
3. Check the property name and its capitalisation against the endpoint reference.
**HTTP status:** `400`
**`message`:** `Bad input data`
**`moreInfo`:**
```text theme={null}
Missing amount property
Missing GatewayReference property
```
**Reason.** A field the operation cannot run without was absent. Which field is required depends on the operation: a capture or refund needs the `GatewayReference` of the original authorisation, and an amount is required wherever money moves.
**How to resolve.**
1. Add the field named in `moreInfo`.
2. For a capture, refund or void, send the `GatewayReference` returned by the original transaction rather than your own reference.
3. Send the amount in the units the gateway expects, and check whether it takes minor units.
**HTTP status:** `400`
**`message`:** `Bad input data`
**`moreInfo`:**
```text theme={null}
Cannot obtain client certificate
```
**Reason.** The profile or gateway configuration names a client certificate for mutual TLS, but it could not be loaded. This is a configuration problem on the account, not a fault in your request.
**How to resolve.**
1. Check the certificate is uploaded against the account and the profile names it exactly.
2. Check the certificate has not expired.
3. Contact [support](https://pcibooking.net/pci-booking-support/) with the profile name if both look correct. Certificate installation is done on the PCI Booking side.
## Card requests
**HTTP status:** `404`
**`message`:** `Uri not found`
**`moreInfo`:**
```text theme={null}
Card request not found
Card request with the specified requestID was not found
```
**Reason.** No card request exists for the `requestID` given. Card requests are not permanent: once completed or expired, a request is no longer retrievable.
**How to resolve.**
1. Check the `requestID` is the one returned when the request was created.
2. Check the request has not already been completed by the cardholder, or passed its expiry.
3. Confirm the credential belongs to the account that created the request.
## When to contact support
Some conditions cannot be resolved from your side. Contact [support](https://pcibooking.net/pci-booking-support/) when:
* A `-1003` persists after you have ruled out deletion, environment and association. Support can tell you whether a token was deleted, and by which user.
* Calls that used to work start failing with `-1003` across the whole account at once, which suggests a processing allowance block.
* A `-150` repeats on the same well-formed request.
* A client certificate is named correctly but cannot be loaded.
Include the `code`, `message` and `moreInfo` verbatim, the endpoint and HTTP method, the token URI or your own reference, and whether the call was against sandbox or production.
## Related
* [Return Codes](/reference/return-codes) - flat lookup table of every code
* [Card Validation Errors](/reference/card-validation-errors) - card number, expiration and CVV validation detail
* [Troubleshooting](/reference/troubleshooting) - symptom-first guide when you do not have an error code
* [API Conventions](/reference/api-conventions) - request and response formats