Error Handling

All errors in the Sent API v3 follow a consistent JSON envelope format with structured error codes, making it easy to programmatically handle errors and troubleshoot issues.

Error Response Format

All errors follow a consistent JSON envelope:

{
  "success": false,
  "status": 404,
  "error": {
    "code": "RESOURCE_001",
    "message": "Contact not found",
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": {
    "request_id": "req_a1b2c3d4e5f60718",
    "timestamp": "2026-01-15T10:30:00Z",
    "version": "v3"
  }
}

Top-level Fields

An error response carries no data field.

Error Object Fields

details and doc_url are omitted rather than sent as null, so read them defensively.

Meta Object Fields

HTTP Status Codes

Error Code Reference

The Error Catalog is the canonical enumeration of every error code, with causes and step-by-step remediation. The codes below are the ones client code most commonly branches on:

For the full AUTH_*, VALIDATION_*, RESOURCE_*, BUSINESS_*, CONFLICT_*, SERVICE_*, and INTERNAL_* listings, refer to the Error Code Quick Reference in the Error Catalog.

Example Validation Error with Details (POST /v3/messages with an empty to array and a template missing both id and name):

{
  "success": false,
  "status": 400,
  "error": {
    "code": "VALIDATION_001",
    "message": "Request validation failed",
    "details": {
      "to": ["'to' must contain at least one recipient"],
      "template": ["'template' must have either 'id' (non-empty GUID) or 'name' (non-empty string)"]
    },
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": { ... }
}

Send-time Error Codes (ERR_*)

These codes are produced by the per-message send pipeline. They are not returned in the HTTP response. POST /v3/messages responds 202 for the batch, and each message is finalized asynchronously with a terminal status. The ERR_* code is Sent's internal classification: what you receive is the public reason_code it maps to, with a reason sentence beside it.

Read each message's outcome, and its reason_code and reason, through:

• GET /v3/messages/{id}: the status field carries the terminal status, and reason_code and reason sit beside it and on the matching event
• GET /v3/messages/{id}/activities: the FILTERED or FAILED activity carries the same pair
• The message.filtered and message.failed webhook events, as payload.reason_code and payload.reason

Every other way a message can end FAILED, FILTERED or BLOCKED is reported the same way. See Message Outcome Codes for the codes only an outcome can have.

Conversation-window codes

Two send-time codes are not ERR_* prefixed, because they are part of the two-way messaging contract and carry an actionable reason. Like the ERR_* codes, they are not returned on the HTTP response: POST /v3/messages responds 202 and the outcome lands on the message as its terminal status. Both call for an approved template as the first step, but they answer to different rules and a template does not clear both: on SMS, RCS, and auto-detect it opens a 7-day window for a contact who has never replied, while only a recent inbound WhatsApp message opens Meta's 24-hour one.

Each is its own reason_code, on the message and on its webhook. The terminal status differs between them: the conversation gate records BLOCKED (excluded from your deliverability rate, fires message.blocked), while the WhatsApp gate records FAILED. Full causes and remediation: CONVERSATION_TEMPLATE_REQUIRED and WHATSAPP_TEMPLATE_REQUIRED. Window mechanics: Conversation Windows.

Common Error Scenarios

Authentication Issues

Missing API Key

curl -X GET https://api.sent.dm/v3/me
# Response: 401 AUTH_002

Solution: Send the API key, in the x-api-key header or as Authorization: Bearer:

curl -X GET https://api.sent.dm/v3/me \
  -H "x-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Validation Issues

Invalid Phone Number

A POST /v3/messages request with a recipient that is not in E.164 format returns:

{
  "success": false,
  "status": 400,
  "error": {
    "code": "VALIDATION_001",
    "message": "Request validation failed",
    "details": {
      "to": ["Each entry in 'to' must be a valid phone number in E.164 format (e.g. +14155551234)"]
    },
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  }
}

Solution: Use E.164 format for every entry in to:

{
  "to": ["+14155551234"]
}

Resource Not Found

Contact Not Found

{
  "success": false,
  "status": 404,
  "error": {
    "code": "RESOURCE_001",
    "message": "Contact not found",
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  }
}

Solution: Verify the contact ID exists:

curl -X GET https://api.sent.dm/v3/contacts \
  -H "x-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Rate Limiting

Too Many Requests

{
  "success": false,
  "status": 429,
  "error": {
    "code": "BUSINESS_002",
    "message": "Rate limit exceeded",
    "doc_url": "https://docs.sent.dm/reference/api/rate-limits"
  }
}

Response Headers:

Retry-After: 60
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705312800

Solution: Implement exponential backoff and respect the Retry-After header. See Rate Limits for per-endpoint limit values and the full set of rate limit headers.

Related guides

• How to handle Sent API errors: success-flag checks, error-code branching, request-ID logging, client-side validation, and testing error paths with sandbox mode.
• How to retry Sent API requests safely: retry loops that use idempotency keys to prevent duplicate operations.
• How to handle Sent API rate limits: backoff, monitoring, and throttling for 429 responses.