Errors

Every error response from GenieOS uses the same envelope:

{
  "error": {
    "type": "validation_error",          // category — one of the values below
    "code": "schema_contract_violation", // specific code, scoped to type
    "message": "Variable `plan` must be one of [\"hobby\", \"pro\"], got \"founders\".",
    "fields": [                          // present on validation errors
      { "path": "variables.plan", "code": "enum_violation" }
    ],
    "retry_after_seconds": null,         // present on rate_limit_exceeded
    "request_id": "req_01JABC..."        // round-trips into the audit log
  }
}

The status code matches the type:

The codes underneath are stable. We grow the code set with new values rather than renaming or repurposing existing ones, so your error-handling switch is forward-compatible.

Common codes

authentication_error

• missing_authorization_header
• invalid_api_key
• revoked_api_key

permission_denied

• scope_required
• workspace_mismatch
• feature_not_enabled

validation_error

• body_invalid_json
• field_required
• field_type_mismatch
• schema_contract_violation
• idempotency_key_invalid
• unknown_template

conflict

• idempotency_key_mismatch
• idempotency_key_in_progress
• template_version_mismatch
• webhook_signing_secret_in_use

rate_limit_exceeded

• key_rate_limit
• workspace_rate_limit
• concurrent_writes_exceeded

SDK error classes

Both SDKs unwrap the envelope into typed exception classes — no string-matching on message.

import {
  GenieOS,
  GenieOSValidationError,
  GenieOSRateLimitError,
} from '@genie-os/sdk';

try {
  await mg.templates.send({ to, template: 'welcome', variables });
} catch (err) {
  if (err instanceof GenieOSValidationError) {
    for (const f of err.fields) console.warn(f.path, f.code);
    return;
  }
  if (err instanceof GenieOSRateLimitError) {
    await sleep(err.retryAfterSeconds * 1000);
    return retry();
  }
  throw err;
}

from genieos import (
    GenieOS,
    GenieOSValidationError,
    GenieOSRateLimitError,
)

try:
    mg.templates.send(to=to, template="welcome", variables=variables)
except GenieOSValidationError as e:
    for f in e.fields:
        print(f.path, f.code)
except GenieOSRateLimitError as e:
    sleep(e.retry_after_seconds)

The full class hierarchy:

• GenieOSError — base.
  • GenieOSAuthError — 401 / 403.
  • GenieOSNotFoundError — 404.
  • GenieOSValidationError — 422 / 409.
  • GenieOSRateLimitError — 429.
  • GenieOSServerError — 5xx.
  • GenieOSNetworkError — DNS / TCP / TLS / timeout.

request_id

Every response — success or error — carries MailGenius-Request-Id as both a header and (on errors) inside the envelope. Quote it whenever you open a support ticket; it round-trips into the audit log so we can find the exact write you saw.

curl -i ... | grep -i mailgenius-request-id
# MailGenius-Request-Id: req_01JABCXYZQ9V...

What about field-level validation?

The fields[] array on validation_error contains one entry per offending input. Codes you\u2019ll see most often:

This means your form code can do something better than "Something went wrong." See Schema contract for how the contract generates these codes.