To help you identify and fix any errors that you may encounter, our errors follow RFC-7807 standards.
Our errors include the following fields:
type- Link to our developer portal for more information about the error.title- Short description about the error.status- HTTP status code.detail- Longer description about the error.
Depending on the type of error we may return additional fields.
Errors
API error
We can’t process your request. We also return an errors array that contains a message field for each error. The message field provides more detail about the error.
Example code
{
"type": "https://docs.payroc.com/api/errors#api-error",
"title": "Api error",
"status": 500,
"detail": "We are unable to process your request at this time"
"errors": [
{
"message": "Service offline"
}
]
}
Bad request
Your request is missing a parameter, or a value is in the wrong format. To help you identify the parameter, we also return an errors array that contains the following fields for each incorrect parameter:
parameter- Name of the parameter that contains the error.detail- Short description of the error.message- Longer description of the error.
Example code
{
"type": "https://docs.payroc.com/api/errors#bad-request",
"title": "Bad request",
"status": 400,
"detail": "One or more validation errors occurred, see error section for more info",
"errors": [
{
"parameter": "start_time",
"detail": "invalid date",
"message": "Expected time, got \\\"\\\" for start_time"
}
]
}
Cannot be canceled
You can't cancel the instruction because the instruction failed or the payment device completed the instruction.
If the payment device completed the instruction, our gateway also returns a link to the resource.
Example code
Instruction failed
{
"type": "https://docs.payroc.com/api/errors#cannot-be-canceled",
"title": "Cannot be canceled",
"status": 409,
"detail": "You cannot cancel this resource in its current state",
"errors": [
{
"message": "Failed instruction cannot be canceled",
"parameter": "signatureInstructionId"
}
],
}
Payment device completed the instruction
{
"type": "https://docs.payroc.com/api/errors#cannot-be-canceled",
"title": "Cannot be canceled",
"status": 409,
"detail": "You cannot cancel this resource in its current state",
"errors": [
{
"message": "Completed instruction cannot be canceled",
"parameter": "signatureInstructionId"
}
],
"link": {
"rel": "signature",
"method": "GET",
"href": "https://api.payroc.com/v1/signatures/M2MJOG6O2Y"
}
}
Cannot be modified
You attempted to change a resource that can't be changed.
Example code
{
"type": "https://docs.payroc.com/api/errors#cannot-be-modified",
"title": "Cannot be modified",
"status": 409,
"detail": "You cannot modify this resource in its current state"
}
Capability not supported
The terminal can't run the action that you requested. We return an errors array that contains a message field for each error. The message field provides more information about the action that failed.
Note: To make changes to your terminal capabilities, contact our Integrations Team at payroc-integrations@payroc.com.
Example code
{
"type": "https://docs.payroc.com/api/errors#capability-not-supported",
"title": "Capability not supported",
"status": 400,
"detail": "The terminal does not support the capability you are trying to use",
"errors": [
{
"parameter": "processingTerminalId",
"message": "Processing terminal does not support subscriptions"
}
]
}
Card type is not supported
You can't run transactions with the card type that you provided in the request.
Example code
{
"type": "https://docs.payroc.com/api/errors#card-type-not-supported",
"title": "Card type is not supported",
"status": 400,
"detail": "You cannot process transactions with 'card_type' cards through this account"
}
Contract already signed
We couldn’t resend the email because the merchant already signed the contract.
Example code
{
"type": "https://docs.payroc.com/api/errors#contract-already-signed",
"title": "Contract already signed",
"status": 400,
"detail": "The merchant has already signed the contract"
}
Currency is not supported
You can't process transactions with the currency that you provided in the request.
Example code
{
"type": "https://docs.payroc.com/api/errors#currency-not-supported",
"title": "Currency is not supported",
"status": 400,
"detail": "You cannot process 'currency_code' transactions through this account"
}
Daily Discount and RewardPayChoice conflict
You can't select Daily Discount with a RewardPayChoice pricing plan. To select Daily Discount, choose a different pricing plan.
To keep the RewardPayChoice pricing plan, don't select Daily Discount.
Example code
{
"type": "https://docs.payroc.com/api/errors#daily-discount-and-reward-pay-conflict",
"title": "Cannot select Daily Discount and RewardPayChoice at the same time.",
"status": 400,
"detail": "Choose a different pricing plan or don't select Daily Discount."
}
Duplicate unique reference
Temporary description — pending review. A payment receipt with the same unique reference already exists. The response has HTTP status 409.
Check the returned detail for information about the duplicate reference. Detailed recovery guidance is being prepared.
Forbidden
You don’t have permission to perform the action that you requested.
Example code
{
"type": "https://docs.payroc.com/api/errors#forbidden",
"title": "Forbidden",
"status": 403,
"detail": "You do not have the required permissions to perform this action"
}
Funding accounts limit reached
Funding accounts restricted. You can not have any more than two funding accounts attached to this entity.
Example code
{
"type": "https://docs.payroc.com/api/errors#funding-accounts-limit-reached",
"title": "Funding accounts limit reached",
"status": 400,
"detail": "You can not have any more than two funding accounts attached to this entity",
}
Funding accounts restricted
You created funding instructions for a funding account that can't receive funds.
If the status of the funding account is pending or rejected, the funding account can't receive funds. To check the status of a funding account, send a GET request to the Funding Accounts endpoint.
Example code
{
"type": "https://docs.payroc.com/api/errors#funding-accounts-restricted",
"title": "Funding accounts restricted",
"status": 400,
"detail": "One or more funding accounts are restricted and can't receive funding instructions",
"errors": [
{
"fundingAccountId": 123,
"message": "Funding account on hold"
}
]
}
Idempotency key in use
You supplied an idempotency key that you used in a previous request. Idempotency keys must be unique.
Example code
{
"type": "https://docs.payroc.com/api/errors#idempotency-key-in-use",
"title": "Idempotency-Key in use",
"status": 409,
"detail": "'Idempotency-Key' is already in use against a different request",
}
Idempotency key missing
Your request didn't contain an idempotency key. You must supply a unique idempotency key for POST requests and PATCH requests.
Example code
{
"type": "https://docs.payroc.com/api/errors#idempotency-key-missing",
"title": "Idempotent-key header missing",
"status": 400,
"detail": "An 'Idempotency-Key' must be supplied for this request",
}
Insufficient funds
You don't have enough funds to send to your merchant. View the balance of your funding account to check what funds are available to send to your merchant.
Example code
{
"type": "https://docs.payroc.com/api/errors#insufficient-funds",
"title": "Insufficient funds",
"status": 400,
"detail": "You do not have the required funds to complete this transaction",
}
Internal server error
Temporary description — pending review. The API gateway encountered an unexpected error while handling your request. The response has HTTP status 500.
Check the returned detail for information about the error. Detailed troubleshooting and retry guidance is being prepared.
KYC check failed
We didn't create your entity because it failed our Know Your Customer (KYC) check.
Example code
{
"type": "https://docs.payroc.com/api/errors#kyc-check-failed",
"title": "Failed KYC Checks",
"status": 400,
"detail": "Entity has been rejected due to failing KYC checks",
}
Method not supported
Temporary description — pending review. The endpoint does not support the HTTP method used in your request. The response has HTTP status 405.
Check the HTTP method and URL against the endpoint's API reference. Detailed troubleshooting guidance is being prepared.
National ID in use
One or more supplied national IDs are not unique. All national IDs must be unique.
Example code
{
"type": "https://docs.payroc.com/api/errors#national-id-in-use",
"title": "National ID in use",
"status": 409,
"detail": "One or more supplied national IDs are not unique. All national IDs must be unique"
}
No control prong or authorized signatory
Your request didn’t indicate which owner is the control prong or the authorized signatory. Set one owner as the control prong or the authorized signatory.
Example code
{
"type": "https://docs.payroc.com/api/errors#no-control-prong-or-authorized-signatory",
"title": "No control prong or authorized signatory",
"status": 400,
"detail": "Set one owner as the control prong or the authorized signatory"
}
No pricing agreement exists for the processing account
We couldn’t resend the email because there is no pricing agreement for the processing account.
Example code
{
"type": "https://docs.payroc.com/api/errors#no-pricing-agreement-exists-for-the-processing-account",
"title": "No pricing agreement exists",
"status": 400,
"detail": "There is no pricing agreement linked to the processing account"
}
Not acceptable
We can’t send a response in the MIME-type format that you requested. We return responses only in application/json.
Example code
{
"type": "https://docs.payroc.com/api/errors#not-acceptable",
"title": "Not acceptable",
"status": 406,
"detail": "Resource does not support the representation requested"
}
Not authorized
We can’t verify your identity.
If you receive this error from our Identity Service, make sure that the API key is valid. Test API keys work only with test requests, and live API keys work only with live requests. For more information, see Authentication.
If you successfully authenticate with our Identity Service but receive a 401 error from our API, the reason for the error might be due to one of the following reasons:
- Authorization header missing - Include your Bearer token in the Authorization header of all requests you send to our API.
- Bearer token expired - Generate a new Bearer token before the current one expires. Each Bearer token expires after one hour.
- Bearer token not valid - Make sure that the Bearer token doesn’t contain an error, for example, if you have truncated the token.
Example code
{
"type": "https://docs.payroc.com/api/errors#not-authorized",
"title": "Not authorized",
"status": 401,
"detail": "Your identity could not be verified"
}
Not found
We can’t find the resource that you requested. We also return a resource field that contains the name of the resource. Make sure that you have included the correct URI.
Example code
{
"type": "https://docs.payroc.com/api/errors#not-found",
"title": "Not found",
"status": 404,
"detail": "Resource not found",
"resource": "account"
}
Not requested by email
We couldn't resend the email to the merchant because you didn't originally choose to send the information by email.
Example code
{
"type": "https://docs.payroc.com/api/errors#not-requested-by-email",
"title": "Not requested by email",
"status": 400,
"detail": "You can use the Reminders endpoint only for information that we sent by email",
}
Payload too large
Your payload is too large. If you’re uploading a document, make sure that each attachment is less than 6MB.
Example code
{
"type": "https://docs.payroc.com/api/errors#payload-too-large",
"title": "Payload too large",
"status": 413,
"detail": "The payload submitted is too large"
}
Processing terminal was not accepted
The terminal can't run your request. We return an errors array that contains a message field for each error. The message field provides more information about the error.
Example code
{
"type": "https://docs.payroc.com/api/errors#processing-terminal-not-accepted",
"title": "Processing terminal was not accepted",
"status": 400,
"detail": "The processing terminal is unable to handle the request, see error section for more info",
"errors": [
{
"parameter": "processingTerminalId",
"message": "Processing terminal has been deactivated"
}
]
}
Recipient amount value limit exceeded
Your account has a funding limit for each recipient, and the amount.value for one or more recipients in the funding instruction exceeds that limit.
Example code
{
"type": "https://docs.payroc.com/api/errors#recipient-amount-value-limit-exceeded",
"title": "Recipient amount.value limit exceeded",
"status": 400,
"detail": "One or more recipients exceed the 'amount.value' limit for your account",
}
Resource already exists
You attempted to create a resource that already exists.
Example code
{
"type": "https://docs.payroc.com/api/errors#resource-already-exists",
"title": "Resource already exists",
"status": 409,
"detail": "The resource you attempted to create already exists",
}
Search too broad
Your request has produced a list of results that is too large. Narrow your search criteria.
Example code
{
"type": "https://docs.payroc.com/api/errors#search-too-broad",
"title": "Search too broad",
"status": 400,
"detail": "Your request has produced a list of results that is too large."
}
Tax ID in use
The tax ID that you supplied is already in use. Supply a unique tax ID.
Example code
{
"type": "https://docs.payroc.com/api/errors#tax-id-in-use",
"title": "Tax ID already in use",
"status": 409,
"detail": "The tax ID that you supplied is already in use. Supply a unique tax ID"
}
Too many control prongs
Your request included more than one owner as the control prong. You can set only one owner as the control prong.
Example code
{
"type": "https://docs.payroc.com/api/errors#too-many-control-prongs",
"title": "Too many control prongs",
"status": 400,
"detail": "You can set only one owner as the control prong"
}
Unsupported media type
Your payload is the wrong format. If you’re uploading a document, make sure that your attachments are in one of the following formats:
- application/pdf
- image/png
- image/bmp
- image/gif
- image/jpeg
- image/heic
- image/heif
Example code
{
"type": "https://docs.payroc.com/api/errors#unsupported-media-type",
"title": "Unsupported media type",
"status": 415,
"detail": "You submitted a payload in an unsupported format"
}
Volume limit has been reached
This request exceeds the processing limit that we permit on your account. We return an errors array that contains a detail field and a message field for each error. The message field provides more information about the error.
Example code
{
"type": "https://docs.payroc.com/api/errors#volume-limit-reached",
"title": "Volume limit has been reached",
"status": 400,
"detail": "You have exceeded the processing volume limit for your account.",
"errors": [
{
"parameter": "order.amount",
"detail": "Above maximum",
"message": "'amount' must not exceed USD 500"
}
]
}