skills/resend-cli/references/error-codes.md

# Error Codes

All errors exit with code `1` and output JSON to **stderr**:

```json
{"error":{"message":"Human-readable description","code":"error_code"}}
```

## Authentication Errors

| Code | Cause | Resolution |
|------|-------|------------|
| `auth_error` | No API key found from any source | Set `RESEND_API_KEY` env, pass `--api-key`, or run `resend login` |
| `missing_key` | `login` called non-interactively without `--key` | Pass `--key "$RESEND_API_KEY"` (from env/secret manager, never a literal) |
| `invalid_key_format` | API key does not start with `re_` | Use a valid Resend API key starting with `re_` |
| `validation_failed` | Resend API rejected the key during login | Verify the key exists and is active at resend.com/api-keys |

## Email Errors

| Code | Cause | Resolution |
|------|-------|------------|
| `missing_body` | None of `--text`, `--html`, `--html-file`, or `--react-email` provided | Provide at least one body flag |
| `react_email_build_error` | Failed to bundle a React Email `.tsx` template with esbuild | Check the template compiles; ensure `react` and one of `react-email` (6.0+), `@react-email/components` (5.x), or `@react-email/render` are installed in the project |
| `react_email_render_error` | Bundled template failed during `render()` | Check the component exports a default function and renders valid React Email markup |
| `file_read_error` | Could not read file from a `--file`/`--html-file`/`--text-file` path | Check file path exists and is readable |
| `send_error` | Resend API rejected the send request | Check from address is on a verified domain; check recipient is valid |

## Contact Import Errors

| Code | Cause | Resolution |
|------|-------|------------|
| `missing_file` | `contacts imports create` called non-interactively without `--file` | Pass `--file <path>` to the CSV to import |
| `invalid_column_map` | `--column-map` is not valid JSON, or is not an object | Pass a JSON object mapping contact fields to CSV headers, e.g. `{"email":"Email"}` |
| `invalid_topics` | `--topics` is not valid JSON, or is not an array | Pass a JSON array of `{id, subscription}` objects |
| `create_error` | Resend API rejected the import (e.g. CSV missing the required `email` column, or file over 100MB) | Ensure the CSV has an `email` column (or map it with `--column-map`) and is under 100MB |

## Domain Errors

| Code | Cause | Resolution |
|------|-------|------------|
| `domain_error` | Domain creation, verification, or update failed | Check domain name is valid; check DNS records are configured |

## General Errors

| Code | Cause | Resolution |
|------|-------|------------|
| `unexpected_error` | Unhandled exception | Check CLI version with `resend update`; report at github.com/resend/resend-cli/issues |
| `unknown` | Error without a specific code | Inspect the `message` field for details |

## Troubleshooting

### "No API key found" in CI
Ensure `RESEND_API_KEY` is set in the environment. The CLI does not prompt in non-TTY mode.

### "Missing required flags" errors
In non-interactive mode (CI, piped, agent), ALL required flags must be provided. The CLI will not prompt.

### Deletion commands fail without `--yes`
All `delete`/`rm` subcommands require `--yes` in non-interactive mode to prevent accidental deletion.

### API rate limits
The Resend API has rate limits. If you hit them, the error message will indicate rate limiting. Add delays between batch operations.

### Scheduled email errors
`--scheduled-at` must be a valid ISO 8601 datetime. The scheduled time must be in the future.