Skip to main content

​
Error schema

Resend uses standard HTTP response codes for success and failure notifications, and errors are further classified by type.

​
invalid_idempotency_key

  • Status: 400
  • Message: Idempotency keys, if present, must have between 1 and 256 characters.
  • Suggested action: Retry with a valid idempotency key.

​
validation_error

  • Status: 400
  • Message: An error was found with one or more fields in the request.
  • Suggested action: The message will contain more details about what field and error were found.

​
missing_api_key

  • Status: 401
  • Message: Missing API key in the authorization header.
  • Suggested action: Include the following header in the request: Authorization: Bearer YOUR_API_KEY.

​
restricted_api_key

  • Status: 401
  • Message: This API key is restricted to only send emails.
  • Suggested action: Make sure the API key has Full access to perform actions other than sending emails.

​
email_above_quota

  • Status: 403
  • Message: You can’t retrieve this email’s content because it was above quota when received.
  • Suggested action: Upgrade your plan to increase your quota.

​
invalid_permission

  • Status: 403
  • Message: Access token is missing required scopes.
  • Suggested action: Request an access token that includes the scopes required by this endpoint.

​
restricted_api_key

  • Status: 403
  • Message: API key is not active
  • Suggested action: Check the API key on the API Keys page and create a new one if needed.

​
suspended_api_key

  • Status: 403
  • Message: This API key is suspended
  • Suggested action: Contact support if you believe this is a mistake.

​
validation_error

  • Status: 403
  • Message: You can only send testing emails to your own email address (youremail@domain.com). To send emails to other recipients, please verify a domain at resend.com/domains, and change the from address to an email using this domain.
  • Suggested action: In Resend’s Domain page, add and verify a domain for which you have DNS access. This allows you to send emails to addresses beyond your own. Learn more about resolving this error.

​
validation_error

  • Status: 403
  • Message: The domain.com domain is not verified. Please, add and verify your domain.
  • Suggested action: Make sure the domain in your API request’s from field matches a domain you’ve verified in Resend. Update your API request to use your verified domain, or add and verify the domain you’re trying to use. Learn more about resolving this error.

​
validation_error

  • Status: 403
  • Message: The example.com domain has been registered already.
  • Suggested action: Verify you are signed in to the correct Resend account and check whether a teammate already added the domain. If you still cannot access it, contact support. Learn more about resolving this error.

​
not_found

  • Status: 404
  • Message: The requested endpoint does not exist.
  • Suggested action: Change your request URL to match a valid API endpoint.

​
method_not_allowed

  • Status: 405
  • Message: Method is not allowed for the requested path.
  • Suggested action: Change your API endpoint to use a valid method.

​
concurrent_idempotent_requests

  • Status: 409
  • Message: There is another request in progress with the same idempotency key.
  • Suggested action: Try the request again later.

​
invalid_idempotent_request

  • Status: 409
  • Message: This idempotency key has been used with this HTTP method and endpoint within the last 24 hours, but the request body was modified and doesn’t match the original request.
  • Suggested action: Change your idempotency key or payload.

​
resource_locked

  • Status: 409
  • Message: Another request is already updating this resource.
  • Suggested action: Retry the request after a short delay.

​
invalid_attachment

  • Status: 422
  • Message: Attachment must have either a content or path.
  • Suggested action: Attachments must either have a content (strings, Buffer, or Stream contents) or path to a remote resource (better for larger attachments).

​
invalid_parameter

  • Status: 422
  • Message: The parameter must be a valid UUID.
  • Suggested action: Check the value and make sure it’s valid.

​
missing_required_field

  • Status: 422
  • Message: The request body is missing one or more required fields.
  • Suggested action: Check the error message to see the list of missing fields.

​
missing_required_parameter

  • Status: 422
  • Message: The request is missing one or more required parameters.
  • Suggested action: Check the error message to see the list of missing parameters.

​
daily_quota_exceeded

  • Status: 429
  • Message: You have exceeded your daily email sending quota.
  • Suggested action: Upgrade your plan to remove the daily quota limit or wait until 24 hours have passed. Both sent and received emails count towards this quota.

​
monthly_quota_exceeded

  • Status: 429
  • Message: You have exceeded your monthly email sending quota.
  • Suggested action: Upgrade your plan to increase the monthly email quota. Both sent and received emails count towards this quota.

​
rate_limit_exceeded

  • Status: 429
  • Message: Too many requests. Please limit the number of requests per second. Or contact support to increase rate limit.
  • Suggested action: Read the response headers and reduce the rate at which you request the API. This can be done by introducing a queue mechanism or reducing the number of concurrent requests per second. If you have specific requirements, contact support to request a rate increase.

​
application_error

  • Status: 500
  • Message: An unexpected error occurred.
  • Suggested action: Try the request again later. If the error does not resolve, check our status page for service updates.

​
service_unavailable

  • Status: 503
  • Message: API is temporarily unavailable
  • Suggested action: Try the request again later. Check our status page for service updates.