# 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:

```json
{
  "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

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

> **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)
```

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://postman-v2.guides.gov.sg/technical-users-api/api-reference/api-errors.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.