Skip to main content
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:
1

The code

Narrows the class of failure, and maps to the HTTP status. See the table below.
2

The moreInfo string

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.
3

The endpoint you called

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.
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: 401message: Missing authentication headermoreInfo: one of the following, depending on which scheme the endpoint uses:
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
HTTP status: 401message: You are not authorized to access this resource. Please contact customer support.moreInfo:
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
HTTP status: 401message: You are not authorized to access this resource. Please contact customer support.moreInfo: one of the following, depending on which check failed:
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 with your account name to have the allowance reviewed and the block lifted.
HTTP status: 401message: You are not authorized to access this resource. Please contact customer support.moreInfo:
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: 404message: Uri not foundmoreInfo:
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: 404message: Uri not foundmoreInfo:
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: 404message: Uri not foundmoreInfo:
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: 400message: Bad input datamoreInfo:
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
HTTP status: 400message: Bad input parametermoreInfo:
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: 400message: Bad input datamoreInfo:
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: 403message: This operation is not allowed for the given entitymoreInfo:
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: 400message: Bad input datamoreInfo: the wording depends on which endpoint you called:
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 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, Target Profiles
HTTP status: 400message: Bad input datamoreInfo:
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
HTTP status: 400message: Bad input datamoreInfo:
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: 400message: Bad input datamoreInfo:
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: 400message: Bad input datamoreInfo:
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: 400message: Bad input datamoreInfo:
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: 400message: Bad input datamoreInfo:
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: 504message: Request timed outmoreInfo: 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

​
Request format

HTTP status: 400message: Message badly formattedmoreInfo:
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

​
Payment gateway

HTTP status: 400message: Bad input datamoreInfo:
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: 400message: Bad input datamoreInfo:
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: 400message: Bad input datamoreInfo:
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: 400message: Bad input datamoreInfo:
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 with the profile name if both look correct. Certificate installation is done on the PCI Booking side.

​
Card requests

HTTP status: 404message: Uri not foundmoreInfo:
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 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.