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"
    }
  ]
}

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 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"
}

Capabilities missing

The terminal can't run the action. 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#capabilities-missing",
  "title": "Capabilities missing",
  "status": 400,
  "detail": "The terminal does not support the capability you are trying to use.", 
  "errors": [
    {
      "parameter": "processingTerminalId",
      "message": "Processing terminal does not support pre-authorizations"
    }
  ]
}

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"
}

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",
}

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",
}

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. This can occur if your Bearer token has expired.

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"
    }
  ]
}

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"
    }
  ]
}