Status Codes & Errors

This page explains how InstaMessage uses HTTP status codes and error responses across the API.

Understanding these responses will help you handle errors correctly, retry requests safely, and track message delivery reliably.

InstaMessage uses standard HTTP status codes to indicate the result of an API request.

Messaging operations are asynchronous, meaning a successful API response confirms acceptance — not delivery.

These responses indicate that the request was accepted or processed successfully.

Important
A successful response (including 201 Created) means the request was accepted — not delivered.
Message delivery outcomes are reported later via webhooks or the Message Status API.

These responses indicate an issue with the request itself.

InstaMessage does not currently return 403, 404, or 409 responses.
Invalid resources or IDs are reported as 400 Bad Request with a specific error code.

These responses indicate an error on the InstaMessage platform or an upstream provider.

All error responses follow a consistent JSON structure:

{
  "code": 4006,
  "message": "Invalid phone number"
}

For batch operations (if supported in future), partial failures may be reported per item.

All error responses include the following fields:

Sending a message is an asynchronous operation.

This means:

• A successful API response confirms acceptance, not delivery
• Delivery, failure, or read status is reported later

Message outcomes are available via:

• Webhooks (message.status)
• Message Status API (lookup by message_id)

Never assume message delivery based on an HTTP response alone.

Webhook delivery is best-effort.

• Webhooks are not retried if your endpoint fails
• Events may arrive out of order
• Missed events can be recovered via the Message Status API

For reliability:

• Respond with 200 OK immediately
• Process events asynchronously
• Store delivery updates idempotently using message_id and status

You may retry requests when encountering:

• Network timeouts
• 5xx server errors

Always ensure retries are idempotent to avoid duplicate actions.

Do not retry requests that return:

• 400 or 422 errors (fix the request instead)
• 401 Unauthorized (fix authentication)

{
  "code": 4006,
  "message": "Invalid phone number"
}

{
  "code": 4001,
  "message": "Missing required field: to"
}

• Always check HTTP status codes before assuming success
• Treat message creation as asynchronous
• Use webhooks for real-time delivery updates
• Use the Message Status API as a fallback
• Store and correlate message_id values
• Never assume delivery from a 2xx response alone

• Send messages → Send a Message
• Track delivery → Delivery Receipts & Message Status
• Receive events → Webhook Quick-Start
• Manage contacts → Contacts
• Handle inbound replies → Inbound Messages & Replies

Understanding status codes and errors ensures your integration is reliable, predictable, and production-ready.