Reference

Error Codes & Troubleshooting

Complete reference for all CLI error codes and SDK error classes, with solutions for each.

CLI Error Codes

Credential Errors

Code	Message	Solution
`CREDENTIALS_NOT_FOUND`	AWS credentials not found	Run wraps aws setup or configure AWS CLI
`CREDENTIALS_EXPIRED`	AWS credentials have expired	Refresh with aws sso login or update access keys
`INVALID_CREDENTIALS`	AWS credentials are invalid	Check access key and secret key are correct

IAM & Permission Errors

Code	Message	Solution
`MISSING_PERMISSIONS`	Insufficient IAM permissions	Run wraps permissions to see required permissions
`ROLE_NOT_FOUND`	IAM role not found	Run wraps email init to create the role
`OIDC_PROVIDER_ERROR`	Failed to create OIDC provider	Check if provider already exists in IAM console

Stack & Deployment Errors

Code	Message	Solution
`STACK_NOT_FOUND`	Pulumi stack not found	Run wraps email init to create infrastructure
`STACK_CONFLICT`	Stack operation in progress	Wait for the current operation to complete
`DEPLOYMENT_FAILED`	Infrastructure deployment failed	Check AWS CloudFormation console for details

Email Errors

Code	Message	Solution
`DOMAIN_NOT_VERIFIED`	Domain not verified in SES	Run wraps email domains verify -d yourdomain.com
`SES_SANDBOX`	SES is in sandbox mode	Follow production access guide
`SENDING_DISABLED`	Email sending not enabled	Run wraps email upgrade to enable sending

SMS Errors

Code	Message	Solution
`PHONE_NOT_VERIFIED`	Phone number not verified	Run wraps sms verify-number
`SMS_SANDBOX`	SMS in sandbox mode	Register toll-free number with wraps sms register
`OPT_OUT`	Recipient opted out	Remove from opt-out list or use different number

SMTP Errors

Code	Message	Solution
`SMTP_CREDENTIALS_FAILED`	SMTP credentials creation failed	Check IAM permissions for SES
`SMTP_CONNECTION_FAILED`	Cannot connect to SMTP endpoint	Verify region and port (587 or 465)

State Errors

Code	Message	Solution
`METADATA_NOT_FOUND`	Connection metadata not found	Run wraps email init or wraps email restore
`METADATA_CORRUPT`	Connection metadata is corrupt	Delete ~/.wraps/connections/ and re-init
`CONFIG_NOT_FOUND`	wraps.config.ts not found	Run wraps email templates init

Template Errors

Code	Message	Solution
`TEMPLATE_COMPILE_ERROR`	Template compilation failed	Check React component syntax
`TEMPLATE_NOT_FOUND`	SES template not found	Run wraps email templates push

SDK Error Classes

Email SDK (`@wraps.dev/email`)

SESError

Thrown when an AWS SES API call fails.

Property	Type	Description
`code`	string	MessageRejected, Throttling, AccountSuspended, MailFromDomainNotVerified
`requestId`	string	AWS request identifier
`retryable`	boolean	Whether the request can be retried

DynamoDBError

Thrown when an email history read/write operation fails.

Property	Type	Description
`code`	string	DynamoDB error code
`requestId`	string	AWS request identifier
`retryable`	boolean	Whether the request can be retried

ValidationError

Thrown when input parameters are invalid.

Property	Type	Description
`field`	string	Which field failed validation
`message`	string	Human-readable error description

SMS SDK (`@wraps.dev/sms`)

SMSError

Thrown when an AWS End User Messaging API call fails.

Property	Type	Description
`code`	string	AWS error code
`retryable`	boolean	Whether the request can be retried

ValidationError

Thrown when input parameters are invalid.

Property	Type	Description
`field`	string	Which field failed validation
`message`	string	Human-readable error description

OptedOutError

Thrown when the recipient has opted out of receiving messages.

Property	Type	Description
`phoneNumber`	string	The phone number that opted out

RateLimitError

Thrown when the sending rate limit has been exceeded.

Property	Type	Description
`retryAfter`	number	Seconds to wait before retrying

No Automatic Retries

The SDKs do NOT automatically retry failed requests. If retryable is true, implement your own retry logic using the pattern below.

Retry Pattern

Use exponential backoff when retrying failed requests. This example uses a simple retry loop with increasing delays.

retry-pattern.ts

import { WrapsEmail, SESError } from '@wraps.dev/email';const email = new WrapsEmail();async function sendWithRetry(params, maxRetries = 3) {  for (let attempt = 0; attempt < maxRetries; attempt++) {    try {      return await email.send(params);    } catch (error) {      if (error instanceof SESError && error.retryable && attempt < maxRetries - 1) {        await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000));        continue;      }      throw error;    }  }}

Error Handling Example

Catch and handle specific error types to provide appropriate responses in your application.

error-handling.ts

import { WrapsEmail, SESError, DynamoDBError, ValidationError } from '@wraps.dev/email';const email = new WrapsEmail();try {  await email.send({    from: 'hello@yourdomain.com',    to: 'user@example.com',    subject: 'Hello',    html: '<p>Hello!</p>',  });} catch (error) {  if (error instanceof ValidationError) {    console.error('Invalid input:', error.field, error.message);  } else if (error instanceof SESError) {    console.error('SES error:', error.code, error.retryable);  } else if (error instanceof DynamoDBError) {    console.error('DynamoDB error:', error.code, error.retryable);  }}

Next Steps

Email SDK

Full API reference for the @wraps.dev/email TypeScript SDK.

View Reference

SMS SDK

Full API reference for the @wraps.dev/sms TypeScript SDK.