API Error Codes and Error Responses

​

Error Response Format

{
  "message": "Error description explaining what went wrong"
}

​

HTTP Status Codes

​

2xx Success

• 200 OK - Request succeeded
• 201 Created - Resource created successfully
• 202 Accepted - Message accepted for processing; inspect each recipient’s status

​

4xx Client Errors

​

400 Bad Request

• Invalid UUID format for account_id or resource IDs
• Malformed email addresses
• Invalid time formats (expecting RFC3339)
• Parameters outside allowed ranges (e.g., limit not between 1-100)
• Invalid domain names or URLs
• Malformed request body

{
  "message": "invalid account_id"
}

{
  "message": "invalid from_time, provide a valid RFC3339 time string"
}

​

401 Unauthorized

• Missing Authorization header
• Invalid API key format (must be Bearer <api_key>)
• API key doesn’t exist or has been revoked
• Account associated with API key is suspended
• API key doesn’t belong to the specified account

{
  "message": "Missing or malformed bearer token"
}

{
  "message": "Invalid API key"
}

{
  "message": "Account is suspended"
}

​

403 Forbidden

• API key lacks required scopes (e.g., trying to delete domains without domains:delete:all or domains:delete:{domain} scope)
• Attempting to access resources outside your API key’s domain restrictions
• Insufficient permissions for specific operations

{
  "message": "Insufficient permissions for the required scope"
}

{
  "message": "api key does not have sufficient permissions to read webhooks"
}

​

404 Not Found

• Resource ID doesn’t exist
• Resource was deleted
• Resource belongs to a different account

{
  "message": "account not found"
}

{
  "message": "domain not found"
}

​

409 Conflict

• Idempotency conflicts: Another request with the same idempotency key is already in progress
• Resource conflicts: Trying to create a resource that already exists (e.g., duplicate domain)
• IP allow list conflicts: Updating your own key would exclude the caller’s current IP

{
  "message": "A request with this idempotency key is already in progress"
}

{
  "message": "domain already exists"
}

​

422 Unprocessable Entity

​

429 Too Many Requests

{
  "message": "Too many requests, rate limited."
}

​

5xx Server Errors

​

500 Internal Server Error

{
  "message": "Internal server error"
}

{
  "message": "internal server error, please try again later"
}

​

Validation Errors

​

Request Body Validation

{
  "message": "invalid request body"
}

​

Field-Specific Validation

{
  "message": "invalid domain name, please provider a valid fully qualified domain name."
}

{
  "message": "limit must be between 1 and 100"
}

​

Security-Related Validation

{
  "message": "domain is banned to protect our network from abuse and spammers. if you think this is an error please contact support"
}

​

Scope and Permission Errors

​

Missing Scopes

{
  "message": "sender domain not found in api key scopes"
}

​

Invalid API Key Context

{
  "message": "invalid api key context"
}

​

Best Practices

​

Error Handling

• Always check the HTTP status code first
• Show the message field to people; do not branch on its text, which can change
• Implement appropriate retry logic for 5xx errors
• Respect rate limits when receiving 429 responses

​

Common Fixes

• 400 errors: Validate your request parameters and JSON structure
• 401 errors: Check your API key and authentication headers
• 403 errors: Verify your API key has the required scopes
• 404 errors: Confirm the resource exists and belongs to your account
• 429 errors: Implement exponential backoff in your retry logic

​

Related Guides

• API authentication, Permission scopes, Send-only API keys.
• REST sending guide, SMTP settings, CLI quickstart.
• Node.js SDK, Go SDK, Idempotency rules.
• API rate limits.