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:

Track each message's outcome through:

• GET /v3/messages/{id}: the status field carries the terminal status (FILTERED or FAILED)
• GET /v3/messages/{id}/activities: a FILTERED or FAILED activity; activity description values are generic (Message updated to FILTERED) and do not carry the ERR_* code or reason
• The message.filtered and message.failed webhook events

The ERR_* code and detailed reason are recorded internally and are not currently included in API responses or webhook payloads. Contact support@sent.dm with the message ID if you need the exact reason.

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.

Like the ERR_* codes, neither is currently exposed in API responses, webhook payloads, or the dashboard. The client-visible signal is the terminal status, which differs between them: the conversation gate records BLOCKED (excluded from your deliverability rate, fires message.blocked), while the WhatsApp gate records FAILED. Infer the cause from the send conditions, or contact support@sent.dm with the message ID. 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_001

Solution: Include the x-api-key header:

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: 200
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.