Error Catalog

This catalog lists every error message the legacy Sent API v2 returns, with its cause and remediation. The entry codes (AUTH-001, VAL-002, and so on) are catalog identifiers for lookup on this page; they do not appear in API responses. For the response structure and status-code overview, see the Error Reference; for retry and error-handling implementation patterns, see How to handle Sent API errors.

Authentication Errors (401)

AUTH-001: Invalid or Missing API Credentials

Error: "Invalid or missing API credentials" Cause: The x-api-key header is missing, or the key does not belong to the customer in x-sender-id. Remediation:

• Include the x-api-key header on every request
• Verify the key is active on the API Keys page of your dashboard and matches your sender ID
• Generate a new API key if the key was rotated or deleted

curl -H "x-api-key: your-api-key-here" \
     -H "x-sender-id: your-sender-id" \
  https://api.sent.dm/v2/contacts

AUTH-002: Missing or Invalid Sender Identifier

Error: "Missing or invalid sender identifier" Cause: The x-sender-id header is missing or its value is not a valid UUID. Remediation: Include the x-sender-id header with your sender ID exactly as shown on the API Keys page of your dashboard.

Validation Errors (400)

VAL-001: Required Field Missing

Errors:

• "Phone number is required": phoneNumber on message sends, number lookup, and contact lookup by phone
• "Custom message is required": customMessage on quick message
• "Contact ID is required": id on contact lookup by ID
• "Message ID is required": id on message lookup
• "Template ID is required": id on template lookup and delete
• "Template body is required": template definition body on template creation

Remediation: Include the named field with a non-empty value.

VAL-002: Invalid ID Format

Errors:

• "Invalid contact ID format. Expected a valid GUID."
• "Invalid message ID format. Expected a valid GUID."
• "Invalid template ID format. Expected a valid GUID."

Cause: The provided ID is not a valid UUID. Remediation: Use the UUID exactly as returned by the API (for example, 550e8400-e29b-41d4-a716-446655440000).

VAL-003: Invalid Pagination Parameters

Errors:

• GET /v2/contacts: "Page must be zero or greater" and "PageSize must be greater than zero"
• GET /v2/templates: "Page must be greater than or equal to 0" and "PageSize must be between 1 and 1000"

Remediation: Use page >= 0 and a positive pageSize (at most 1000 for templates).

VAL-004: Template Variable Validation Failed

Errors:

• "Missing required template variables: {names}"
• "Variable '{name}' is invalid: param text cannot have new-line/tab characters or more than 4 consecutive spaces."
• "Variable '{name}' does not match the required pattern."

Cause: The templateVariables map on a send request omits a variable the template requires, or a value violates the format rules. Remediation:

• Provide every variable defined in the template, with names matching exactly
• Remove new-line and tab characters and runs of more than 4 spaces from values
• For variables with a validation pattern, supply a value matching that pattern

Business Logic Errors

BUS-001: Insufficient Balance

Error: "Insufficient balance to send message." HTTP Status: 402 Payment Required Cause: The account balance is below the minimum required to send a message. Remediation: Add funds to your account in the dashboard, then retry the request.

BUS-002: Template Not Found

Error: "Template not found" HTTP Status: 404 Not Found Cause: The templateId on a send request does not exist or does not belong to your customer account. Remediation:

• Verify the template ID against GET /v2/templates
• Confirm the template belongs to the authenticated customer account

Not Found Errors (404)

NOT-001: Resource Not Found

Error: 404 with an empty response body Cause: The contact, message, template, or phone number requested from a GET lookup endpoint (or a template targeted by DELETE) does not exist for the authenticated customer. Remediation:

• Verify the ID or phone number is correct
• Confirm the resource belongs to your customer account

Rate Limit Errors (429)

RATE-001: Rate Limit Exceeded

Error: "Rate limit exceeded. Please retry after {seconds} seconds." Cause: The per-minute limit on the send-message endpoints was exceeded. Remediation: Wait the number of seconds in the Retry-After header, then retry. Limit values and the full 429 response are documented on Rate Limits.

RATE-002: Quick-Message Daily Limit Exceeded

Error: "Daily message limit exceeded. You have sent 5 of 5 allowed messages today. Limit resets at midnight UTC." Cause: POST /v2/messages/quick-message allows 5 messages per customer per day. Remediation: Wait for the reset at midnight UTC, or use POST /v2/messages/phone with your own template for higher volume.

Server Errors (500)

SRV-001: Failed to Queue Message

Error: "Failed to queue message for processing." Cause: The send endpoint could not hand the message to the delivery pipeline. Remediation: Retry the request; contact support if the error persists.

SRV-002: Template Creation Failed

Errors:

• "Failed to create template"
• "Template was created but could not be retrieved"

Cause: POST /v2/templates failed while persisting or reading back the template. Remediation: List your templates to check whether the template was created, then retry if it is absent; contact support if the error persists.

Delivery Failures Are Not API Errors

Message sends are asynchronous: POST /v2/messages/phone and POST /v2/messages/contact return 202 once the message is queued, before any carrier or WhatsApp interaction. Failures that happen later (unreachable numbers, carrier rejections, WhatsApp errors) do not produce an API error response. They surface as a FAILED message status, which you can observe via GET /v2/messages/{id} or a message.failed webhook event.

Webhook delivery problems (timeouts, non-2xx responses from your endpoint) are also handled outside the v2 API surface; see webhook retries.