Skip to main content
After sending a message with the Courier API, you’ll receive a response indicating whether the request was successful and how to track its delivery. Understanding these responses and handling errors correctly ensures reliable delivery and better visibility into message outcomes. This guide explains how to:
  • Interpret success and error responses from the Send API
  • Implement robust error-handling logic in production
  • Monitor message status in the Courier dashboard
  • Receive real-time delivery updates through webhooks
By following these patterns, you can build resilient notification workflows that recover from temporary issues and provide clear delivery insight to your team.

​
Response Handling

​
Success Response

Successful sends return a request ID for tracking: 
{
  "requestId": "87e7c05b-4f46-fda24e356e23"
}

​
Error Responses

If a send request fails, the Courier API returns an error response with an HTTP status code and message explaining the issue. Common error scenarios include:
  • 400: Bad Request - Invalid message format or missing fields
  • 401: Unauthorized - Invalid or expired auth token
  • 500: Internal Server Error - Courier service issue

​
Monitoring & Debugging

​
Message Logs

Message Logs in the Courier dashboard provide real-time visibility into every message your system sends. Each log entry shows the message’s delivery path, status, and any associated errors. This helps you confirm successful sends and troubleshoot failed or delayed deliveries. Common message statuses include:
  • SENT: The message was successfully handed off to the provider.
  • DELIVERED: The provider confirmed successful delivery to the recipient.
  • FAILED: Delivery was not completed. Review error details to identify the cause.
  • THROTTLED: The message was rate limited or blocked by configured guardrails.
Message Status Details: For a full list of message statuses and their definitions, see the Message Logs documentation.

​
Delivery Status Updates via Webhooks

Use webhooks to receive real-time updates when a message’s delivery status changes. Courier sends a message:updated event to your configured webhook endpoint each time a message is sent, delivered, failed, or retried. Webhook events let your application track delivery progress without polling the API. You can use them to update user interfaces, trigger automations, or store delivery data in your own systems. 
{
  "type": "message:updated",
  "data": {
    "id": "1-6143cf63-4f27670f6304f465462695f2",
    "status": "DELIVERED",
    "recipient": "c156665c-a76c-4440-9676-f25c1b04ba93",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}
Webhook Setup: To receive these notifications, you need to configure outbound webhooks in your Courier workspace. Go to Settings → Outbound Webhooks and add your webhook endpoint URL.Implementation: Your webhook endpoint should return a 200 response quickly and handle the event data asynchronously. For complete webhook setup instructions, including signature verification and event handling, see Outbound Webhooks.

​
Best Practices

​
Error Handling

Implement proper error handling for production use: 
try {
  const { requestId } = await courier.send(messageData);
  console.log(`Message sent successfully: ${requestId}`);
} catch (error) {
  if (error.statusCode === 429) {
    // Rate limited - implement backoff
    console.log("Rate limited, retrying later...");
  } else if (error.statusCode >= 500) {
    // Server error - retry with exponential backoff
    console.log("Server error, retrying...");
  } else {
    // Client error - check request format
    console.log("Invalid request:", error.message);
  }
}