Errors

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

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

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

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

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

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