Errors

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 Code	Description
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:

Property	Type	Description
type	string	The broad category in which this error belongs to in snake-case.
code	string	The identifier of the error that has occured in snake-case.
message	string	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.

error.type	Description
api_error	API errors indicate an issue with PaySG's servers.
external_error	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_error	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_error	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.

error.code	Description
parameter_invalid	A parameter provided in the request has failed validation
api_key_invalid	The API Key provided is invalid
email_blacklisted	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_required	Authentication is required for this request
api_key_expired	The API Key provided has expired
stripe_connect_account_not_found_for_payment_service	The payment service has no Stripe connect account connected to it which is required.
payment_not_found	A payment with the ID provided cannot be found.
payment_service_not_found	A payment service with the ID provided cannot be found.
user_forbidden	The user making this request is not allowed to carry out this operation.
idempotent_request_in_progress	A request with the same idempotency key is currently being processed.
idempotent_request_body_mismatch	Request body does not match initial request with the same idempotency key
server_error	An internal error has occurred on PaySG servers