Bytloop MailDocs
Status

Getting started

  • Introduction
  • Quickstart

Sending email

  • Send a transactional email
  • Sending domains vs mailboxes

Framework guides

  • Send email from Next.js
  • Send email from Ruby on Rails
  • Send email from Django
  • Send email from Laravel

Domains

  • Verify a domain

Receiving email

  • Receive email
  • Webhooks

Reference

  • Rate limits
  • Errors
  • SDKs

Reference

Errors

HTTP status codes, common error codes, and the shape of a Bytloop error response.

Every error response from the Bytloop API shares the same shape, so a single handler can render or log any failure without special-casing the endpoint.

Response shape#

{
  "error": {
    "code": "recipient_suppressed",
    "message": "customer@example.com is on the workspace suppression list.",
    "correlation_id": "cor_2N9pKqRxLvZ8yT",
    "details": {
      "recipient": "customer@example.com",
      "suppressed_at": "2026-03-02T09:14:07.001Z"
    }
  }
}
{
  "error": {
    "code": "recipient_suppressed",
    "message": "customer@example.com is on the workspace suppression list.",
    "correlation_id": "cor_2N9pKqRxLvZ8yT",
    "details": {
      "recipient": "customer@example.com",
      "suppressed_at": "2026-03-02T09:14:07.001Z"
    }
  }
}
  • code — a stable machine-readable identifier. Safe to switch on.
  • message — human-readable, safe to show to a support agent but not to an end user (may reference internal details).
  • correlation_id — the same id also logged on the Bytloop side. Copy it into any support request so we can find your request in seconds.
  • details — optional, code-specific extra fields.

HTTP status codes#

StatusMeaningRetry?
400 Bad RequestMalformed JSON or unknown fields.No — fix the request.
401 UnauthorizedMissing or malformed Authorization header.No.
403 ForbiddenThe key is valid but not authorised for this action or workspace.No.
404 Not FoundThe path or resource does not exist.No.
409 ConflictIdempotency-Key collision with a different body.No — pick a new key.
422 Unprocessable EntityValidation failed — see code for specifics.Depends on the code.
429 Too Many RequestsRate or plan cap. See Rate limits.Yes, after Retry-After.
500 Internal Server ErrorSomething broke on our side.Yes, with backoff.
502 Bad Gateway, 503 Service Unavailable, 504 Gateway TimeoutUpstream provider hiccup.Yes, with backoff.

Common error codes#

CodeStatusWhat it means
invalid_request400The body could not be parsed as valid JSON.
missing_field422A required field is absent. details.field names it.
invalid_field422A field is present but the value is malformed.
unauthenticated401The bearer token is missing, malformed, or revoked.
insufficient_scope403The key does not have permission for this endpoint.
domain_not_verified422The from domain has no verified record.
recipient_suppressed422Recipient is on the workspace suppression list.
attachment_too_large422Combined attachment size exceeds 15MB.
rate_limited429Per-key or per-workspace throttle.
plan_cap_reached429Monthly send cap exhausted for this billing period.
idempotency_conflict409Same Idempotency-Key used with a different body.
webhook_endpoint_disabled422The endpoint you tried to enqueue an event on is auto-disabled.
internal_error500Unhandled server-side failure. Retry with backoff and include the correlation id if it persists.

Handling errors well#

Three principles:

  1. Switch on code, log message. Only the code is stable across releases; message wording can and will change.
  2. Retry idempotently. Use Idempotency-Key on every mutating call. 429 and 5xx are safe to retry; other statuses usually are not.
  3. Surface correlation_id on any user-visible failure. It is the single fastest way to get support unblocked.

Programmatic reference

The API explorer shows the exact error shapes each endpoint can return, including any endpoint-specific fields on details.

PreviousRate limitsNextSDKs

On this page

  • Response shape
  • HTTP status codes
  • Common error codes
  • Handling errors well