Error Catalog

This catalog is the canonical reference for Sent API v3 error codes. Every documented code appears below with its cause and step-by-step remediation; other documentation pages link to this catalog rather than restating code details.

Authentication Errors

AUTH_001: User is not authenticated

Error Message: "User is not authenticated"

HTTP Status: 401 Unauthorized

Cause: The request is missing the required x-api-key header.

Remediation:

1. Ensure you're including the x-api-key header in all API requests
2. Verify the header name is exactly x-api-key (case-sensitive)
3. Check that your API key is being loaded from environment variables correctly

Example Fix:

# ❌ Missing header
curl -X GET https://api.sent.dm/v3/me

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

AUTH_002: Invalid or missing API key

Error Message: "Invalid or missing API key"

HTTP Status: 401 Unauthorized

Cause: The provided API key is invalid, revoked, or the x-api-key header is present but its value is not recognized.

Remediation:

1. Verify your API key is correct and complete
2. Check that you're using the API key for the correct environment (each environment should have its own key)
3. Log into your Sent Dashboard and verify the key is active
4. Generate a new API key if the current one was revoked

AUTH_004: Insufficient permissions

Error Message: "Insufficient permissions for this operation"

HTTP Status: 403 Forbidden

Cause: Your user role doesn't have permission to perform this operation.

Remediation:

1. Check your organization role (owner, admin, developer, billing)
2. Contact your organization owner to request additional permissions
3. Some operations require the owner or admin role

See: Roles and Permissions for the operations each role can perform and how to look up your own role

AUTH_005: Account not yet activated

Error Message: "Your account is not yet activated. Please wait for account activation before using the API."

HTTP Status: 403 Forbidden

Cause: The API key is valid and channel setup is complete, but the account is still pending final activation by Sent.

Remediation:

1. You have completed all required setup steps, so no action is needed from your side
2. Wait for the activation confirmation email from Sent
3. Contact support@sent.dm if activation takes longer than expected

AUTH_006: KYC verification not complete

Error Message: "Your KYC verification is not complete. Please submit your KYC documents before using the API."

HTTP Status: 403 Forbidden

Cause: The API key is valid but the account has not completed KYC verification. Applies to accounts in status: SIGNED_UP, KYC_STARTED, WHITELISTED, ONBOARDING_STARTED, or KYC_RESUBMISSION_REQUESTED.

Remediation:

1. Log into your Sent Dashboard and complete the KYC verification flow
2. If resubmission was requested, address the flagged items and resubmit your documents
3. Contact support@sent.dm if you need assistance with KYC

AUTH_007: Channel setup not complete

Error Message: "Your channel setup is not complete. Please configure at least one messaging channel before using the API."

HTTP Status: 403 Forbidden

Cause: The API key is valid and KYC is approved, but no messaging channel (SMS or WhatsApp) has been configured. Applies to accounts in status: KYC_COMPLETED or MESSAGE_COMPLIANCE_COMPLETED.

Remediation:

1. Log into your Sent Dashboard and complete channel setup
2. Configure at least one SMS or WhatsApp sender
3. See Channel Setup for step-by-step instructions

Validation Errors

VALIDATION_001: Request validation failed

Error Message: "Request validation failed"

HTTP Status: 400 Bad Request

Cause: The request body or parameters failed validation. Check the details field for specific field-level errors.

Remediation:

1. Review the error.details object for field-specific error messages
2. Ensure all required fields are provided
3. Verify data types match the schema (for example, strings vs numbers)

Example:

{
  "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)"]
    }
  }
}

VALIDATION_002: Invalid phone number format

Error Message: "Invalid phone number format"

HTTP Status: 400 Bad Request

Cause: The phone number is not in a valid format.

Remediation:

1. Use E.164 format: +1234567890
2. Include the country code (for example, +1 for US)
3. Remove any non-numeric characters except the leading +

Valid Examples:

• +1234567890 (US)
• +447911123456 (UK)
• +919876543210 (India)

VALIDATION_003: Invalid GUID format

Error Message: "Invalid GUID format"

HTTP Status: 400 Bad Request

Cause: A UUID field contains an invalid format.

Remediation:

1. Ensure UUIDs follow the format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
2. Verify the UUID is complete (36 characters including hyphens)
3. Check that you're not passing an empty string or null

Valid Example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

VALIDATION_004: Required field is missing

Error Message: "Required field is missing"

HTTP Status: 400 Bad Request

Cause: A required field is not present in the request body.

Remediation:

1. Check the API documentation for required fields
2. Ensure the field name is spelled correctly (snake_case)
3. Verify the field is not null or undefined

VALIDATION_005: Field value out of valid range

Error Message: "Field value out of valid range"

HTTP Status: 400 Bad Request

Cause: A numeric field value is outside the allowed minimum/maximum range.

Remediation:

1. Check the API documentation for valid ranges
2. For retry_count: must be between 1 and 5
3. For timeout_seconds: must be between 5 and 120
4. Ensure integer values are not negative where prohibited

Example:

{
  "error": {
    "code": "VALIDATION_005",
    "message": "Field value out of valid range",
    "details": {
      "retry_count": ["Value must be between 1 and 5"]
    }
  }
}

VALIDATION_006: Invalid enum value

Error Message: "Invalid enum value"

HTTP Status: 400 Bad Request

Cause: A field value is not one of the allowed enum values.

Remediation:

1. Check the API documentation for allowed values
2. Verify the value matches exactly (case-sensitive)
3. Common enums: channel (sms, whatsapp), template category (MARKETING, UTILITY, AUTHENTICATION)

VALIDATION_007: Invalid Idempotency-Key format

Error Message: "Invalid Idempotency-Key format"

HTTP Status: 400 Bad Request

Cause: The idempotency key doesn't meet the format requirements.

Remediation:

1. Use only alphanumeric characters, hyphens, and underscores
2. Keep the key between 1 and 255 characters
3. Avoid special characters such as spaces, @, and #

Valid Examples:

• req-abc-123
• send_msg_001
• webhook_retry_1

Resource Errors

RESOURCE_001: Contact not found

Error Message: "Contact not found"

HTTP Status: 404 Not Found

Cause: The specified contact ID doesn't exist or doesn't belong to your account.

Remediation:

1. Verify the contact ID is correct
2. List all contacts to find the correct ID: GET /v3/contacts
3. Check that you're using the correct API key for the account that owns the contact

Debug Steps:

# List contacts to find valid IDs
curl -X GET https://api.sent.dm/v3/contacts \
  -H "x-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

RESOURCE_002: Template not found

Error Message: "Template not found"

HTTP Status: 404 Not Found

Cause: The specified template ID doesn't exist.

Remediation:

1. Verify the template ID is correct
2. List all templates: GET /v3/templates
3. Ensure the template hasn't been deleted

RESOURCE_003: Message not found

Error Message: "Message not found"

HTTP Status: 404 Not Found

Cause: The specified message ID doesn't exist.

Remediation:

1. Verify the message ID is correct
2. Note that message IDs are only available after sending
3. Messages may be purged after retention period

RESOURCE_004: Customer not found

Error Message: "Customer not found"

HTTP Status: 404 Not Found

Cause: The specified customer ID doesn't exist or is not accessible.

Remediation:

1. Verify the customer ID is correct
2. Check that your API key has access to this customer
3. Contact support if the customer should exist

RESOURCE_005: Organization not found

Error Message: "Organization not found"

HTTP Status: 404 Not Found

Cause: The specified organization ID doesn't exist or you don't have access.

Remediation:

1. Verify the organization ID is correct
2. Ensure you're using an organization-level API key
3. Check that your account is a member of the organization

RESOURCE_006: User not found

Error Message: "User not found"

HTTP Status: 404 Not Found

Cause: The specified user ID doesn't exist in your organization.

Remediation:

1. Verify the user ID is correct
2. List organization users to find valid IDs
3. The user may have been removed from the organization

RESOURCE_007: Resource already exists

Error Message: "Resource already exists"

HTTP Status: 409 Conflict

Cause: Attempting to create a resource that already exists (for example, a duplicate contact).

Remediation:

1. Check if the resource already exists using a list or get endpoint
2. Update the existing resource instead of creating
3. Use a unique identifier for your idempotency key

RESOURCE_008: Webhook not found

Error Message: "Webhook not found"

HTTP Status: 404 Not Found

Cause: The specified webhook ID doesn't exist.

Remediation:

1. Verify the webhook ID is correct
2. List all webhooks: GET /v3/webhooks
3. Check if the webhook was deleted

RESOURCE_009: Brand not found

Error Message: "Brand not found for this profile"

HTTP Status: 404 Not Found

Cause: No 10DLC brand is registered for the profile, and none is inherited from its organization.

Remediation:

1. Register the brand first; see the 10DLC Registration Guide
2. Confirm you are targeting the right profile with GET /v3/profiles

RESOURCE_010: Campaign not found

Error Message: "Campaign not found for this profile"

HTTP Status: 404 Not Found

Cause: The specified campaign ID doesn't belong to this profile's brand.

Remediation:

1. List the profile's campaigns and reuse the returned id
2. Verify the campaign belongs to the brand registered for this profile

RESOURCE_011: Batch not found

Error Message: "Batch not found"

HTTP Status: 404 Not Found

Cause: The specified batch SMS operation doesn't exist.

Remediation:

1. Verify the batch ID is correct
2. Check whether the batch has expired or was already processed

RESOURCE_012: Phone number not found

Error Message: "Phone number not found"

HTTP Status: 404 Not Found

Cause: The specified phone number isn't provisioned on your account.

Remediation:

1. List your numbers to confirm the exact value
2. Use E.164 format (for example, +14155550123)

RESOURCE_013: Resource not found

Error Message: "Resource not found"

HTTP Status: 404 Not Found

Cause: Generic not-found fallback, returned when no more specific code applies.

Remediation:

1. Verify the resource ID in the request path
2. Check the endpoint path is correct for the resource type

RESOURCE_014: Profile not found

Error Message: "Profile not found"

HTTP Status: 404 Not Found

Cause: The specified profileId isn't a child profile of your organization. Passing your organization's own ID also fails.

Remediation:

1. Use a profile ID returned by GET /v3/profiles
2. Confirm the profile belongs to your organization

Business Logic Errors

BUSINESS_001: Cannot modify inherited contact

Error Message: "Cannot modify inherited contact"

HTTP Status: 422 Unprocessable Entity

Cause: You're attempting to modify a contact that was inherited from a parent organization or shared profile.

Remediation:

1. Create a new contact with the desired phone number
2. Contacts inherited from parent organizations are read-only
3. Use your own profile-scoped API key for contact modifications

BUSINESS_002: Rate limit exceeded

Error Message: "Rate limit exceeded"

HTTP Status: 429 Too Many Requests

Cause: You've exceeded the allowed number of requests per minute.

Remediation:

1. Check the Retry-After header for wait time
2. Implement exponential backoff in your code
3. Consider using webhooks instead of polling
4. Contact support if you need higher limits

See: Rate Limits Documentation

BUSINESS_003: Insufficient account balance

Error Message: "Insufficient balance"

HTTP Status: 402 Payment Required

Cause: Your account doesn't have enough credit to complete the operation.

Note: POST /v3/messages does not return this error. Sends are accepted with 202; when the balance is insufficient, each message is finalized asynchronously as BLOCKED and clears after a top-up. Legacy v2 send endpoints reject an out-of-balance request synchronously with this error.

Remediation:

1. Check your current balance and add funds in Billing → Overview (the balance is not exposed through the API)
2. Review pricing for the operation you're attempting

BUSINESS_004: Contact has opted out

Error Message: "Contact has opted out of messaging"

HTTP Status: 422 Unprocessable Entity

Cause: An operation targeted a contact that has opted out of messaging.

Note: POST /v3/messages does not return this error. Sends are accepted with 202 regardless of recipient opt-out state, and each consent-blocked message is finalized asynchronously as FILTERED (see ERR_CONSENT_BLOCKED below).

Remediation:

1. Inspect the affected contacts via GET /v3/contacts/{id} and confirm their opt_out status.
2. Remove opted-out contacts from your messaging lists.
3. Re-engagement requires the contact to opt back in through a STOP/START style flow or via an opt_out: false update to the contact (where you have a verifiable record of new consent).

ERR_CONSENT_BLOCKED: Per-message consent block

Where it surfaces:

• GET /v3/messages/{id}: status = FILTERED
• GET /v3/messages/{id}/activities: a FILTERED activity; its description is the generic Message updated to FILTERED
• The message.filtered webhook event

The ERR_CONSENT_BLOCKED code and the consent-block reason are recorded internally and are not included in API responses or webhook payloads. A FILTERED terminal status indicates a policy block (consent or routing); check the contact's opt_out field to confirm a consent block.

Cause: The send-time consent policy refused this individual message because the recipient's contact has opt_out = true or their phone is on the customer's phone-channel suppression list. The check runs pre-routing, so no provider call is made and the customer is not charged.

Remediation:

1. Stop targeting this contact until they re-confirm consent.
2. If the opt-out is incorrect (for example, test data), update the contact's opt_out field through PATCH /v3/contacts/{id}. Only do this when you have a verifiable record of renewed consent.
3. For phone-level suppression entries that should be removed, contact support.

BUSINESS_005: Template not approved

Error Message: "Template not approved for sending"

HTTP Status: 422 Unprocessable Entity

Cause: The WhatsApp template hasn't been approved yet.

Remediation:

1. Check template status: GET /v3/templates/{id}
2. Wait for WhatsApp/Meta approval (typically 24-48 hours)
3. For urgent needs, use SMS channel instead
4. Review template guidelines to ensure approval

BUSINESS_006: Message cannot be modified in current state

Error Message: "Message cannot be modified in current state"

HTTP Status: 422 Unprocessable Entity

Cause: The message has already been sent or is in a final state that prevents modification.

Remediation:

1. Messages can only be modified while in QUEUED or ACCEPTED status
2. Once a message is SENT, DELIVERED, READ, or FAILED, it cannot be modified
3. Send a new message if you need to make changes

BUSINESS_007: Channel not available

Error Message: "Channel not available for this contact"

HTTP Status: 422 Unprocessable Entity

Cause: The requested messaging channel (SMS/WhatsApp) isn't available for this phone number.

Remediation:

1. Check available channels for the contact:

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

2. Use an available channel from available_channels
3. Don't specify a channel to let the API choose automatically

BUSINESS_008: Operation would exceed quota

Error Message: "Operation would exceed quota"

HTTP Status: 422 Unprocessable Entity

Cause: The operation would exceed your account's quota limits, such as those for messages, contacts, or templates.

Remediation:

1. Check your current usage in the Dashboard
2. Upgrade your plan to increase quotas
3. Delete unused resources to free up quota
4. Contact support for temporary quota increases

Conflict Errors

CONFLICT_001: Concurrent idempotent request

Error Message: "Concurrent idempotent request in progress"

HTTP Status: 409 Conflict

Cause: Another request with the same idempotency key is currently being processed.

Remediation:

1. Wait for the original request to complete
2. Use a unique idempotency key for each distinct operation
3. Don't reuse idempotency keys across different operations

Service Errors

SERVICE_001: Cache service temporarily unavailable

Error Message: "Cache service temporarily unavailable. Please retry your request."

HTTP Status: 503 Service Unavailable

Cause: The cache backing idempotency processing is unavailable, so the API cannot guarantee your request is not a duplicate. Returned on requests that carry an Idempotency-Key header while the cache is down.

Remediation:

1. Retry the request after a short delay, reusing the same Idempotency-Key
2. Check API Status for known issues

Internal Errors

INTERNAL_001: Unexpected internal server error

Error Message: "Unexpected internal server error"

HTTP Status: 500 Internal Server Error

Cause: An unexpected error occurred on the server.

Remediation:

1. Retry the request after a short delay
2. If the error persists, contact support with:
   • The request_id from the response
   • Timestamp of the error
   • The operation you were attempting

INTERNAL_002: Database operation failed

Error Message: "Database operation failed"

HTTP Status: 500 Internal Server Error

Cause: An unexpected database error occurred while processing your request.

Remediation:

1. Retry the request after a short delay
2. If the error persists, contact support with the request ID
3. This is typically a transient issue

INTERNAL_003: External service error

Error Message: "External service error (SMS/WhatsApp provider)"

HTTP Status: 502 Bad Gateway

Cause: The upstream messaging provider is experiencing issues.

Remediation:

1. Wait a few minutes and retry
2. Check API Status for known issues
3. The message is queued and retried automatically

INTERNAL_004: Timeout waiting for operation

Error Message: "Timeout waiting for operation"

HTTP Status: 504 Gateway Timeout

Cause: The operation timed out while waiting for an external service or internal processing.

Remediation:

1. The operation may still be in progress - check the resource status
2. Retry the request with the same idempotency key
3. Contact support if timeouts persist

INTERNAL_005: Service temporarily unavailable

Error Message: "Service temporarily unavailable"

HTTP Status: 503 Service Unavailable

Cause: The API is temporarily unavailable due to maintenance or high load.

Remediation:

1. Retry with exponential backoff
2. Check API Status
3. Wait for service restoration

Troubleshooting Guide

General Troubleshooting Steps

1. Check the Error Code: Use the error code to find its entry in this catalog
2. Review Request ID: Include meta.request_id when contacting support
3. Verify API Version: Ensure you're using v3 endpoints (/v3/)
4. Test in Sandbox Mode: Use sandbox: true to validate without side effects

Getting Help

If you can't resolve an error:

1. Documentation: Check this catalog and the Error Handling guide
2. Support email: support@sent.dm
3. Include in Support Request:
   • Request ID (meta.request_id)
   • Error code and message
   • Timestamp of occurrence
   • Endpoint and method
   • Request payload (sanitized)

Error Code Quick Reference

Every code documented on this page, in page order: