Status discriptions

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.

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 Endpoint

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

HTTP 400 - Validation error#

HTTP 400 - Payment already exist#

HTTP 400 - Limit was reached#

HTTP 401 - Unauthorized#

HTTP 403 - Forbidden Endpoint#

HTTP 403 - Forbidden IP Address#

HTTP 423 - Temporary error#

HTTP 400 - Validation error

HTTP 400 - Payment already exist

HTTP 400 - Limit was reached

HTTP 401 - Unauthorized

HTTP 403 - Forbidden Endpoint

HTTP 403 - Forbidden IP Address

HTTP 423 - Temporary error