Error Catalog

Comprehensive catalog of all errors you may encounter when using the Sent API v3, including their causes and step-by-step remediation steps.

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 expired API key

Error Message: "Invalid or expired API key"

HTTP Status: 401 Unauthorized

Cause: The provided API key is invalid, expired, or has been revoked.

Remediation:

1. Verify your API key is correct and complete
2. Check that you're using the correct key type (live vs test)
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 owner or admin privileges

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 (e.g., strings vs numbers)

Example:

{
  "error": {
    "code": "VALIDATION_001",
    "message": "Request validation failed",
    "details": {
      "phone_number": ["Phone number is required"],
      "template_id": ["Invalid UUID format"]
    }
  }
}

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 (e.g., +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_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-255 characters
3. Avoid special characters like spaces, @, #, etc.

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_007: Resource already exists

Error Message: "Resource already exists"

HTTP Status: 409 Conflict

Cause: Attempting to create a resource that already exists (e.g., 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

Business Logic Errors

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 account balance"

HTTP Status: 422 Unprocessable Entity

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

Remediation:

1. Add funds to your account in the Dashboard
2. Check your current balance: GET /v3/me
3. 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: The contact has opted out of receiving messages.

Remediation:

1. Remove the contact from your messaging lists
2. Do not attempt to message opted-out contacts
3. Respect the contact's preferences per compliance requirements

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_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

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

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_003: External service error

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

HTTP Status: 502 Bad Gateway

Cause: The upstream messaging provider (Twilio, Meta) is experiencing issues.

Remediation:

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

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 specific guidance above
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 Test Mode: Use test_mode: 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