Errors¶

How the Mailyte API reports errors, what the status codes mean, and how to handle them.

Error Response Format¶

Error responses follow one envelope:

{
  "type": "error",
  "msg": "Human-readable error description",
  "correlation_id": "a1b2c3d4e5f6"
}

• Every response carries an X-Correlation-Id header, and every JSON error body (status ≥ 400) has the same correlation_id folded in. Quote it when reporting problems -- every server log line for the request carries it too.
• Errors that need a stable machine-readable identifier additionally carry an error_code field (see the registry below).
• Some errors include a data field with additional detail:

{
  "type": "error",
  "msg": "Validation failed",
  "data": {
    "errors": [
      "Organization name is required",
      "Invalid admin email format"
    ]
  }
}

HTTP Status Codes¶

404 is always preferred over 403 for cross-tenant access: a 403 would confirm the resource exists.

error_code Registry¶

New codes are additive; the absence of an error_code on older errors is expected.

Common Error Messages¶

Authentication and authorization (401/403)¶

See Authentication -- Authentication Errors for the full table. Highlights:

Validation errors (400)¶

Not found (404)¶

Conflicts (409)¶

Dependency errors (400)¶

Service unavailable (503)¶

Note that proxied 503s use the downstream {"error": ...} shape rather than the type/msg envelope.

Error Handling Best Practices¶

1. Always check the type field. If it is "error", something went wrong.

2. Check data.errors for validation failures. When the message is "Validation failed", the data.errors array tells you exactly which fields are wrong.

3. Branch on error_code where present. It is stable across releases; msg wording is not.

4. Retry on 503. Downstream services may be temporarily unavailable. Wait a few seconds and retry -- with an Idempotency-Key on mutating requests so retries are safe.

5. Do not retry on 4xx (except 409 IDEMPOTENCY_IN_PROGRESS, which asks you to retry shortly). Client errors will not succeed without changing the request.

6. Log the correlation_id. It links your request to every server-side log line about it.

Example: Handling Errors in Code¶

import requests

resp = requests.post(
    "http://your-server:8083/api/v1/domains/",
    headers={"X-API-Key": "YOUR_KEY"},
    json={"domain": "acme.com"},
)

body = resp.json()

if body.get("type") == "error":
    code = body.get("error_code")
    if code == "DOMAIN_ALREADY_CLAIMED":
        print("Domain already exists:", body.get("data", {}).get("existing_id"))
    elif resp.status_code == 400 and "errors" in body.get("data", {}):
        for err in body["data"]["errors"]:
            print(f"Validation error: {err}")
    elif resp.status_code == 401:
        print("Check your API key")
    else:
        print(f"Error [{body.get('correlation_id')}]: {body['msg']}")
else:
    print(f"Success: {body['msg']}")

const resp = await fetch("http://your-server:8083/api/v1/domains/", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ domain: "acme.com" })
});

const body = await resp.json();

if (body.type === "error") {
  if (body.error_code === "DOMAIN_ALREADY_CLAIMED") {
    console.error("Domain already exists:", body.data?.existing_id);
  } else if (resp.status === 400 && body.data?.errors) {
    body.data.errors.forEach(err => console.error("Validation:", err));
  } else {
    console.error(`Error [${body.correlation_id}]:`, body.msg);
  }
} else {
  console.log("Success:", body.msg);
}