PaySG uses conventional HTTP response codes to indicate the success or failure of an API request.

In the event of an error occurring, the server will respond with the appropriate error HTTP status code along with a JSON response body containing details about the error that has occurred.

HTTP Status Codes

Generally, codes in the 4XX range indicate an error that occurred due to the information provided (e.g. invalid input, rate limit exceeded). Codes in the 5XX range indicate an error within PaySG’s servers (this should be rare).

Conventional HTTP response codes are used to indicate the success or failure of an API request.

HTTP Status CodeDescription

400 - Bad Request

The request was unacceptable, often due to a missing required parameter or an unexpected format.

401 - Unauthorized

No valid credentials provided.

402 - Request Failed

The parameters were valid but the request failed. 402 is not a clearly defined HTTP code, but in certain APIs is used when a resource’s state is concerned. (eg. Payment service is not connected to a stripe account).

403 - Forbidden

Your credentials doesn’t have permissions to perform the request.

404 - Not Found

The requested resource doesn’t exist.

409 - Conflict

The request conflicts with another request (eg. same idempotent key).

429 - Too Many Requests

Too many requests. We recommend an exponential backoff.

500 - Server Error

Something went wrong on PaySG's end

503 - Server Error

Something went wrong on PaySG’s end, caused by an external service

Response Body

The response body will be a a JSON containing a nested error object with the following properties:




The broad category in which this error belongs to in snake-case.



The identifier of the error that has occured in snake-case.



A human readable string explaining the error that has occurred.

data (optional)

JSON Object

An optional nested JSON object that contain additional contextual information about the error.

To identify the specific error that has occurred, integrators may look at the code field in the error object.

Sample Response

The following is a sample response body returned by the server when an invalid email address has been provided as part of a request.

  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "Param error. Email violates validation"

Error Types (error.type)

The following is a list of possible error types. This will be present in the type field of the error object.



API errors indicate an issue with PaySG's servers.


External errors indicate an issue due to an external service utilized by PaySG, which prevented PaySG from completing the request (Eg. Stripe, Postmark, etc.).


Idempotency errors occur when an Idempotency-Key is re-used on a request that does not match the first request's API endpoint and parameters or when the first request is still processing.


Invalid request errors arise when your request has invalid parameters.

Errors Codes (error.code)

The following is a non-exhaustive list of possible error codes. This will be present in the code field of the error object.



A parameter provided in the request has failed validation


The API Key provided is invalid


Email address has been blacklisted by either PaySG or our email provider. This is commonly due to previous attempts to send to this email address being rejected.


Authentication is required for this request


The API Key provided has expired


The payment service has no Stripe connect account connected to it which is required.


A payment with the ID provided cannot be found.


A payment service with the ID provided cannot be found.


The user making this request is not allowed to carry out this operation.


A request with the same idempotency key is currently being processed.


Request body does not match initial request with the same idempotency key


An internal error has occurred on PaySG servers

Last updated