Errors

When a request fails, the API returns a non-2xx HTTP status and a JSON body in the standard error envelope.

Envelope

{
  "_links": {
    "origin": {
      "href":   "https://c1.emailgistics.com/api/v1/reports/mailboxPerformance",
      "method": "POST",
      "body": {
        "parameters": {
          "mailboxId": "mb_abc123",
          "period":    "last7Days"
        }
      }
    }
  },
  "status": "error",
  "error": {
    "code":    "error_code",
    "message": "Human-readable description of what went wrong."
  }
}

For GET endpoints, _links.origin.method is "GET" and the body field is omitted.

The _links.origin block identifies the request that failed. error.code is a stable identifier you can match on; error.message is for humans and may change.

Status codes

Each endpoint’s reference page lists any error conditions specific to that endpoint.

Retry semantics

The API does not guarantee idempotency for retries. Whether a 5xx is safe to retry depends on the operation:

• POST /reports/* endpoints create new async report runs. A retry after a 5xx may produce a duplicate run — the original request may already have been queued before the failure surfaced. The 3-concurrent-runs cap (see Rate limits) will start returning 429 if you retry aggressively without confirming what’s already running.
• GET endpoints are read-only. Retries are usually harmless, but we don’t formally guarantee that.

If retry safety matters to your integration, structure your client to detect duplicate effects (for example, by deduplicating async runs on the parameters in _links.origin.body) rather than relying on the server to make retries safe.