Errors

Error format

Every /v1 error uses this shape:

{
  "error": {
    "code": "machine_readable_code",
    "message": "Human-readable description",
    "request_id": "req_0123456789abcdef"
  }
}

Additional safe context appears under error.details:

{
  "error": {
    "code": "tenant_limit_reached",
    "message": "Tenant ceiling reached. Upgrade your plan to provision more tenants.",
    "request_id": "req_0123456789abcdef",
    "details": {
      "tenant_limit": 3,
      "connected_tenants_count": 3,
      "remaining_tenants": 0
    }
  }
}

TenantCore does not return raw internal exception strings, credentials, provider tokens, or arbitrary Microsoft/provider error bodies in generic server failures. Use request_id when support needs to trace the underlying operation.

HTTP status codes

Code	Meaning
`200`	Request succeeded
`400`	Invalid request, including a missing/invalid `Idempotency-Key` on writes
`401`	Authentication failed
`402`	API entitlement or account capacity does not allow the operation
`403`	Authenticated account is not allowed to perform the operation
`404`	TenantCore-owned resource was not found for this account
`409`	Request conflicts with current state, including idempotency conflicts/in-progress retries
`410`	A retired API contract was called
`413`	Public API request body exceeds the configured maximum
`422`	Request payload failed schema validation
`429`	Rate limit exceeded; honor `Retry-After`
`500`	TenantCore could not complete the request
`502`	A required upstream/provider operation failed
`503`	TenantCore protection/dependency is temporarily unavailable or API capacity is busy

Security and request-control errors

Code	Status	Description
`invalid_auth_header`	401	`Authorization` is missing or malformed
`missing_api_key`	401	Bearer token is empty
`invalid_api_key`	401	API key does not resolve to an active TenantCore account
`api_key_identity_not_found`	401	TenantCore could not resolve the key to its canonical account UUID
`no_api_plan`	402	Account is not entitled to the public API
`api_access_inactive`	402	API entitlement is currently unusable
`request_body_too_large`	413	`/v1` request body exceeds the configured maximum
`rate_limit_exceeded`	429	Authenticated account quota was exceeded
`preauth_rate_limit_exceeded`	429	Network sent too many requests before authentication
`api_capacity_busy`	503	Per-process concurrency protection is full; retry shortly
`rate_limiter_unavailable`	503	Distributed rate limiter is unavailable; API fails closed
`idempotency_key_required`	400	Write request did not include `Idempotency-Key`
`invalid_idempotency_key`	400	Idempotency key does not meet format requirements
`idempotency_key_conflict`	409	Same key was used for a different request
`idempotency_request_in_progress`	409	Same request is still executing; retry with the same key after `Retry-After`
`idempotency_store_unavailable`	503	Distributed idempotency protection is unavailable; API fails closed

Ownership errors

TenantCore deliberately does not distinguish “this resource exists under another customer” from “this resource does not exist.” Cross-account probes resolve to the same account-scoped not-found behavior.

Code	Status	Description
`tenant_not_found`	404	Tenant is not an owned TenantCore resource for this account
`domain_not_found`	404	Domain is not owned under the requested TenantCore tenant
`mailbox_not_found`	404	Mailbox is not owned under the requested TenantCore tenant

Idempotent retries

When a completed write is repeated with the same Idempotency-Key and exact same request, TenantCore returns the original status/body and adds:

Idempotency-Replayed: true

A new operation must use a new key.

Handling errors in code

import requests

response = requests.get(
    "https://api.tenantcore.io/v1/tenants",
    headers={"Authorization": "Bearer tc_live_your_key"},
)

if not response.ok:
    error = response.json().get("error", {})
    code = error.get("code")
    message = error.get("message")
    request_id = error.get("request_id")
    raise Exception(
        f"TenantCore API [{response.status_code}] {code}: {message} "
        f"(request_id={request_id})"
    )

For writes, include an idempotency key:

headers = {
    "Authorization": "Bearer tc_live_your_key",
    "Idempotency-Key": "create-mailboxes-001",
    "Content-Type": "application/json",
}

Overview

Authentication & Errors

Infrastructure

Sending Tool Integrations

Error format

HTTP status codes

Security and request-control errors

Ownership errors

Idempotent retries

Handling errors in code

​Error format

​HTTP status codes

​Security and request-control errors

​Ownership errors

​Idempotent retries

​Handling errors in code

Error format

HTTP status codes

Security and request-control errors

Ownership errors

Idempotent retries

Handling errors in code