Error discriptions | API PayStar.uk

INFO

This section describes the possible HTTP error statuses returned by the PayStar API. Each API method (such as deposit creation, payout initiation, or status check) may return a status code that indicates the current state of the request or highlights an issue that occurred during processing.

Understanding these statuses helps developers to:

Identify the cause of an error and determine possible solutions;

Implement robust error handling and retry logic;

Display clear and actionable messages to end users.

Most HTTP status codes are consistent across all endpoints. Although they are individually listed in each method's documentation, this centralized section allows you to map and reference them globally.

Refer to the table below for status codes, their meanings, and guidance on how to handle each one during integration.

Payment Status Verification Before Cascading

Errors and missing responses during payment creation may occur due to transient or unforeseen circumstances and do not reliably indicate the final payment status. If you receive a 499+ error, any other error, or no response at all, for example due to a broken connection or timeout, check the payment status in our system before sending the payment through the cascade.

HTTP 400 - Validation error

May happen In payment creation methods:

Deposit H2H

Deposit Token

Deposit H2С

Payout H2H

Description: The request is malformed or contains invalid parameters.
Resolution: There are several possible causes for this error — each cause has its own recommended solution.
Resolution: Add missing fields. Check the full list of fields with your account manager

{
  "label": "VALIDATION_ERROR.",
  "message": "External_transaction_id is required property",
  "statusDescrption": "0-0000"
}

{
  "label": "VALIDATION_ERROR.",
  "message": "Amount is required property",
  "statusDescrption": "0-0000"
}

{
  "label": "VALIDATION_ERROR.",
  "message": "Currency is required property",
  "statusDescrption": "0-0000"
}

{
  "label": "VALIDATION_ERROR.",
  "message": "currency has invalide value",
  "statusDescrption": "0-0000"
}

HTTP 400 - Payment already exist

May happen In payment creation methods:

Deposit H2H

Deposit Token

Deposit H2С

Payout H2H

Description: The request is malformed or contains invalid parameters.
Resolution: There are several possible causes for this error — each cause has its own recommended solution.
Resolution: Check status of a payment with this ID. Create a payment by specifying a unique ID

{
  "label": "VALIDATION_ERROR.",
  "statusDescrption": "1-4007",
  "message": "Order with this external_transaction_id already exist"
}

HTTP 400 - Limit was reached

May happen In payment creation methods:

Deposit H2H

Deposit Token

Deposit H2С

Payout H2H

Description: The request is malformed or contains invalid parameters.
Resolution: There are several possible causes for this error — each cause has its own recommended solution.
Resolution: Confirm with the Account Manager to increase the limit

 {
  "label": "LIMITS_ERROR",
  "message": "Limit id: 5eaf47eb-344c-4aeb-8651-494d649499b5 was reached",
  "statusDescrption": "0001-0",
  "externalTransactionId": null
}

HTTP 401 - Unauthorized

May happen: across all API methods:

Balance | H2H

Deposit H2H

Deposit Token

Deposit H2С

Deposit status H2H

Payout H2H

Payout status H2H

Description: Authentication failed or the API key is missing or invalid.
Resolution: Please verify that your API keys are correct. If the issue persists, contact your Account Manager.
Response example: This response does not have a body.

HTTP 403 - Forbidden pipeline

May happen: across all API methods:

Balance | H2H

Deposit H2H

Deposit Token

Deposit H2С

Deposit status H2H

Payout H2H

Payout status H2H

Description: The client does not have permission to perform this operation.
Resolution: Your authorization keys might not be activated. Please contact your Account manager for assistance.
Response example: This response does not have a body.

HTTP 403 - Invalid pipline type

May happen: across all API methods:

Balance | H2H

Deposit H2H

Deposit Token

Deposit H2С

Deposit status H2H

Payout H2H

Payout status H2H

Description: The API key used does not match the expected endpoint type.
Resolution: Your keys may be active but assigned to a different payment type. For example, you might be attempting a deposit operation using payout-specific credentials. Keep in mind that deposit and payout keys are always distinct and must be used accordingly.
Response example: This response does not have a body.

HTTP 403 - Forbidden IP Address

May happen: across all API methods:

Balance | H2H

Deposit H2H

Deposit Token

Deposit H2С

Deposit status H2H

Payout H2H

Payout status H2H

Description: The IP address from which you are making the request is not added to the whitelist.
Resolution: Contact your Account Manager and request to add your IP address to the whitelist.
Note: After the IP address is added to the whitelist, it typically takes up to 1 hour before you can perform payments or tests.
Response example:

HTTP 404 - Payment not Found

May happen: across Chaeck status methods:

Deposit status H2H

Payout status H2H

Description: The payment with the specified identifier was not found.
Resolution: Please verify that the entered ID is correct.
Response example: This response does not have a body.

HTTP 423 - Temporary error

May happen In payment creation methods:

Deposit H2H

Deposit Token

Deposit H2С

Payout H2H

Description: Error 423 usually occurs when the payment parameters do not match the routing settings. For example, the amount may be below the allowed minimum.
Resolution: Please contact your account manager.
Response example:

{
  "label": "TEMPORARY_ERROR",
  "statusDescrption": "0000-1",
  "message": "There is currently no possibility to make a payment, please try again later"
}

Error descriptions

HTTP 400 - Validation error#

HTTP 400 - Payment already exist#

HTTP 400 - Limit was reached#

HTTP 401 - Unauthorized#

HTTP 403 - Forbidden pipeline#

HTTP 403 - Invalid pipline type#

HTTP 403 - Forbidden IP Address#

HTTP 404 - Payment not Found#

HTTP 423 - Temporary error#

HTTP 400 - Validation error

HTTP 400 - Payment already exist

HTTP 400 - Limit was reached

HTTP 401 - Unauthorized

HTTP 403 - Forbidden pipeline

HTTP 403 - Invalid pipline type

HTTP 403 - Forbidden IP Address

HTTP 404 - Payment not Found

HTTP 423 - Temporary error