API errors

Error codes

This document provides a complete reference of all error codes, messages, and solutions documented in the API guides and codebase.

---

API Error Response Format

Every API error response includes:

{
  "error": {
    "code": "error_code_in_snake_case",
    "message": "Human-readable error message",
    "type": "domain_error",
    "id": "unique_trace_id"
  }
}

Use the id (trace ID) when contacting support. It helps identify the exact request in logs.

---

Error Codes by HTTP Status

400 Bad Request

Error Code	Message	Cause	Solution
parameter_invalid	Invalid recipient, ensure it is a valid normalized phone number, eg 6591112222.	Phone number format is incorrect	Phone number must include country code and be properly formatted (e.g. 6591112222)
parameter_invalid	[language] is not supported. available language(s) for this campaign: [languages]	Invalid or unsupported language	Use only: english, chinese, malay, tamil
parameter_invalid	Validation failed (expected type is object)	Template variables missing or invalid	Ensure all {{variables}} are provided as non-empty strings in an object
parameter_invalid	File too large, max file size is 40MB	CSV file exceeds size limit	Reduce CSV file size or split into multiple files
message_not_found_or_retry_message_not_in_failure_status	Message cannot be retried as it does not exist or it has not failed.	Message not found or not in failure status	Check message exists; only failed messages can be retried
too_many_message_attempts_error	Message can no longer be retried as it has reached the maximum number of attempts of 3.	Message already retried 3 times	Accept failure and create a new message if needed
batch_not_found_or_is_not_retryable	Batch cannot be retried as it does not exist or is currently not retryable.	Batch not found or still processing	Verify batch ID; wait for batch to complete before retrying
unresolved_batch_messages	Batch cannot be retried as there is at least one batch message that is still unresolved.	Some batch messages still processing	Wait for batch to complete; check batch statistics
no_failed_batch_messages_to_retry	Batch cannot be retried as either all messages are successful or all failed messages have exceeded the maximum number of attempts.	All messages succeeded or all failed messages exhausted retries	Check batch statistics; create a new batch if needed
nric_mobile_not_found	Recipient does not have a mobile number mapping	NRIC recipient has no phone number on file	Use phone number instead of NRIC, or verify recipient NRIC

401 Unauthorised

Error Code	Message	Cause	Solution
invalid_api_key_provided	The API key provided is invalid.	API key is incorrect, expired, or deleted	Verify API key format and confirm it is active in the web UI
invalid_ip_address_error	The IP address used for this request is invalid.	Request from non-whitelisted IP	Whitelist your IP in the campaign settings Integrations page

403 Forbidden

Error Code	Message	Cause	Solution
1010	(Varies)	The API key does not have permissions to perform the request	Check to ensure you are using the correct API key

404 Not Found

The requested resource does not exist. Verify the campaign ID, message ID, or batch ID in your request URL.

429 Too Many Requests

Error Code	Message	Cause	Solution
too_many_requests	Too many requests	Rate limit exceeded (default 10 TPS per campaign, shared across all APIs)	Implement exponential backoff; reduce request frequency

500, 502, 503, 504 Server Errors

Something went wrong on Postman's end. These are rare. If persistent, contact support with the trace ID.

---

Message Delivery Errors

These are not API request errors. They appear in the latestStatus of a message after it has been accepted by the API. Query the Retrieve Message endpoint to check delivery status.

Error Types

Delivery errors use two error types:

• delivery_error: Problem delivering the message to the recipient

• server_error: Internal issue with Postman or the aggregator

Error Codes

Error Type	Error Code	Retryable	Test Number (in test.postman.gov.sg)	Description
delivery_error	recipient_invalid	No	65 1111 1111	Recipient's mobile number is not recognised by the network operator. Caused by deactivated numbers, incorrect format, or numbers not released by the regulator.
delivery_error	recipient_unavailable	Yes	65 1111 2222	Recipient's device is not currently connected to the mobile network. Caused by coverage gaps, SIM issues, or device problems.
delivery_error	content_invalid	No	65 1111 3333	Issue with message content, such as prohibited content or incorrect encoding.
delivery_error	routing_error	Maybe	65 1111 4444	Failure routing the message to the recipient's mobile network. Caused by operator routing infrastructure issues or unapproved numbers.
delivery_error	message_expired	Maybe	65 1111 5555	Message was not delivered within the 48-hour timeframe set by SMS aggregators.
delivery_error	delivery_unknown_error	Maybe	65 1111 9999	Exact cause of failure is not identifiable. May relate to recipient device configuration or international restrictions.
server_error	server_unknown_error	Maybe	65 2222 2222	Internal error, typically due to an unknown issue with Postman or the aggregator's server.

Note on retries: Not all messages are suitable for retries, especially OTPs, as the recipient's next step will be to request another OTP. Test numbers are only available in the Postman test environment; do not use them in production.

---

Support Information

When contacting support, include:

1. Error message: The exact error message received

2. Trace ID: The id field from the error response

3. Request details: What you were trying to do (sanitised, no credentials)

4. Timestamp: When the error occurred

5. Reproducibility: Steps to reproduce the error

Example:

Error Code: parameter_invalid
Trace ID: abc123def456
Message: Invalid recipient, ensure it is a valid normalized phone number, eg 6591112222.
When: 2024-01-15 10:30:00
What I was doing: Sending a single message
Phone number: 91112222 (should have been 6591112222)

---