Documentation
Ask or search…
K
Links

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