API Response Formats

HTTP Status Codes

Nomsa uses conventional API Responses Codes to indicate the success or failure of an API request.

Code	Description
200 - OK	Everything worked as expected
201 - Created	Resource created. The message is being sent.
202 - Accepted	We have accepted the request, but processing has not been completed. This is usually used for long-running processes like handling uploads of recipient lists to generate messages for campaigns.
400 - Bad Request	The request was rejected. This is likely caused by missing required parameters or parameters supplied in an incorrect format.
401 - Unauthenticated	Invalid API key provided.
403 - Forbidden	User doesn't have permission to perform the request, could be due to resources are in an invalid state for the operation.
404 - Not Found	The requested resource doesn't exist.
410 - Gone	Data has been redacted from Nomsa.
413 - Content Too Large	Number of attachments or size of attachments exceeded limit.
429 - Too Many Requests	Rate limit exceeded. Too many requests.
500 - Internal Server Error.	Something went wrong on Nomsa's end. (These are rare.)

Format of Successful Responses

All responses to successful requests to the Nomsa API will be returned in JSON format with a HTTP status code in the 2xx range. The response will contain information about the resources that are being acted on (e.g. creation, retrieval).

Sending messages is an asynchronous process. As such, a successful API request to our message sending endpoints simply mean the request has been made successfully. It does not mean that your message has been sent or delivered successfully. To check this, you should call the respective endpoints (email, SMS) to check the status of your message.

The following is an example of a JSON object received after sending an email via the this endpoint of our programmatic email API:

{
    "id": "14",
    "from": "Nomsa <[e-mail]>",
    "recipient": "[e-mail]",
    "params": {
        "body": "Hello here is your OTP: 145863 ",
        "from": "Nomsa <[e-mail]>",
        "subject": "One time OTP",
        "reply_to": "[e-mail]"
    },
    "attachments_metadata": null,
    "status": "ACCEPTED",
    "error_code": null,
    "error_sub_type": null,
    "accepted_at": "2023-10-04T06:45:25.250Z",
    "sent_at": null,
    "delivered_at": null,
    "opened_at": null,
    "created_at": "2023-10-04T06:45:24.821Z",
    "updated_at": "2023-10-04T06:45:25.250Z",
    "classification": "URGENT",
    "tag": "string",
    "cc": [
        "[e-mail]"
    ],
    "bcc": []
}

Format of Error Responses

For error responses (with non-2xx codes), the response will be in JSON format with these fields

{
  "code": "error code for this specific error type",
  "message": "human-readable explanation of the error and possibly the next step"
}

Ideally, most of our errors are expected to happen during development process for your system and to serve as guidelines for your developers. However, some might happen for your production system (for e.g. 429 rate_limit error), in which case, using the code field is a reliable way to programmatically handle those error flows.