Errors

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This endpoint requires the \"subscribers:write\" scope.",
    "doc_url": "https://www.mailneo.co/documentation/api/getting-started#insufficient_scope",
    "request_id": "req_..."
  },
  "meta": { "request_id": "req_..." }
}

• code — the stable contract. A code may be added, but an existing one is never renamed or repurposed. Branch on this.
• type — the broad category (invalid_request_error, authentication_error, permission_error, not_found_error, conflict_error, rate_limit_error, quota_error, api_error), useful for a default handler.
• message — written for a human reading a log. Not stable; do not parse it.
• param — present when one field is at fault, and names it.
• doc_url — a link to this documentation, anchored to the exact code.
• request_id — in both error and meta, so a client written against either placement finds it.

import { MailneoApiError } from "@mailneo/sdk";

try {
  await client.subscribers.create({ email });
} catch (err) {
  if (err instanceof MailneoApiError) {
    // Branch on the stable code, never on the message.
    switch (err.code) {
      case "resource_already_exists":
        return updateInstead(); // it exists and you own it — PATCH it
      case "rate_limit_exceeded":
        return retryAfter(err.retryAfterMs);
      default:
        log.error({ code: err.code, requestId: err.requestId });
        throw err;
    }
  }
  throw err;
}

The catalogue is declared ahead of the features that raise from it, so a code you have never seen may simply not be reachable yet. Individual endpoints do not document their own error responses: this taxonomy applies uniformly, which is the point of having one.

• Per key: 600 requests per 60 seconds. GET /usage separately reports your plan's documented allowance under api.requests_per_minute, which on lower plans is the smaller of the two — pace against whichever is lower, and treat RateLimit-Remaining as the authoritative live figure.
• Per address, before authentication: 120 failed attempts per 60 seconds. Successful requests are not counted, so sharing an egress address with other customers — as every hosted automation platform does — cannot throttle you.

The legacy X-RateLimit-* spellings are sent alongside these for older clients. Prefer the unprefixed names.

Honour Retry-After when present, exponential backoff with jitter otherwise. Retry rate_limit_exceeded, service_unavailable and internal_error. Do not retry an invalid_request_error unchanged — it will fail identically every time. Retry a write only under the same Idempotency-Key, so the retry replays instead of repeating; the idempotency page covers the semantics, and the SDK follows exactly these rules out of the box.