Errors¶

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

Error Response Format¶

All error responses follow the same structure:

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

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¶

Common Error Messages¶

Authentication Errors (401)¶

Authorization Errors (403)¶

Validation Errors (400)¶

Not Found Errors (404)¶

Conflict Errors (409)¶

Dependency Errors (400)¶

Service Unavailable (503)¶

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. Retry on 503. Downstream services may be temporarily unavailable. Wait a few seconds and retry.

4. Do not retry on 4xx. Client errors (400, 401, 403, 404, 409) will not succeed on retry without changing the request.

5. Log the full response. When debugging, log the entire JSON body, not just the status code.

Example: Handling Errors in Code¶

import requests

resp = requests.post(
    "http://your-server:5000/api/v1/organizations",
    headers={"X-API-Key": "YOUR_KEY"},
    json={"id": "acme", "name": "Acme Corp"},
)

body = resp.json()

if body["type"] == "error":
    if 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 == 409:
        print("Resource already exists")
    elif resp.status_code == 401:
        print("Check your API key")
    else:
        print(f"Error: {body['msg']}")
else:
    print(f"Success: {body['msg']}")

const resp = await fetch("http://your-server:5000/api/v1/organizations", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ id: "acme", name: "Acme Corp" })
});

const body = await resp.json();

if (body.type === "error") {
  if (resp.status === 400 && body.data?.errors) {
    body.data.errors.forEach(err => console.error("Validation:", err));
  } else if (resp.status === 409) {
    console.error("Resource already exists");
  } else {
    console.error("Error:", body.msg);
  }
} else {
  console.log("Success:", body.msg);
}