Error codes

All Sluice REST API errors return a JSON response with a consistent shape:

{
  "statusCode": 422,
  "name": "validation_error",
  "message": "Missing required field: to"
}

Error reference

Status	Name	When
`401`	`unauthorized`	Missing or invalid API key
`413`	`payload_too_large`	Request body exceeds 10 MB
`422`	`validation_error`	Missing required fields or invalid format
`429`	`rate_limit_exceeded`	Organization rate limit hit

401 — unauthorized

Missing or invalid API key. Check that your Authorization header includes a valid Bearer token.

curl -X POST https://app.sluice.email/api/v1/emails \
  -H "Content-Type: application/json" \
  -d '{"from": "a@b.com", "to": "c@d.com", "subject": "test", "text": "hi"}'

{
  "statusCode": 401,
  "name": "unauthorized",
  "message": "Missing or invalid API key"
}

Fix: Include a valid API key in the Authorization header:

-H "Authorization: Bearer sl_live_..."

See API keys for key management.

413 — payload_too_large

The total request body exceeds 10 MB. This typically happens with large attachments.

# Sending a file larger than ~7.5 MB (base64 inflates size by ~33%)
curl -X POST https://app.sluice.email/api/v1/emails \
  -H "Authorization: Bearer sl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"from": "a@b.com", "to": "c@d.com", "subject": "big file", "text": "see attached", "attachments": [{"filename": "huge.zip", "content": "<very large base64>"}]}'

{
  "statusCode": 413,
  "name": "payload_too_large",
  "message": "Request body exceeds 10MB limit"
}

Fix: Reduce attachment size or host large files externally and include a download link in the email body instead.

422 — validation_error

The request is missing required fields or contains invalid data.

# Missing "to" field
curl -X POST https://app.sluice.email/api/v1/emails \
  -H "Authorization: Bearer sl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"from": "a@b.com", "subject": "test", "text": "hi"}'

{
  "statusCode": 422,
  "name": "validation_error",
  "message": "Missing required field: to"
}

Required fields: from, to, subject, and at least one of text or html.

Common validation errors:

Message	Cause
`Missing required field: to`	No `to` field in request body
`Missing required field: from`	No `from` field in request body
`Missing required field: subject`	No `subject` field in request body
`Must include text or html body`	Neither `text` nor `html` provided
`Invalid email address`	`from` or `to` is not a valid email address

429 — rate_limit_exceeded

Your organization has hit its rate limit. Rate limits apply across all API keys in the organization.

{
  "statusCode": 429,
  "name": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again in 60 seconds."
}

Fix: Wait for the cooldown period indicated in the response, then retry. If you consistently hit rate limits, contact support to discuss increasing your quota.