Error format
Every error response from the API returns a JSON body in this shape:{
"detail": {
"message": "Human-readable description",
"code": "machine_readable_code"
}
}
{
"detail": {
"message": "Tenant ceiling reached. Upgrade your plan to provision more tenants.",
"code": "tenant_limit_reached",
"plan_name": "API Starter",
"tenant_limit": 25,
"connected_tenants_count": 25,
"remaining_tenants": 0
}
}
HTTP status codes
| Code | Meaning |
|---|---|
200 | Request succeeded |
400 | Bad request — invalid payload, missing field, or constraint violation |
401 | Authentication failed — invalid or missing API key |
402 | Payment required — no active plan, or tenant ceiling reached |
403 | Forbidden — you do not own the resource you are trying to access |
404 | Not found — tenant, domain, or mailbox does not exist on your account |
409 | Conflict — e.g. DNS not yet propagated, or domain already exists |
500 | Internal server error — something went wrong on our side |
Error codes
Authentication errors
| Code | Status | Description |
|---|---|---|
invalid_auth_header | 401 | Authorization header is missing or does not start with Bearer |
missing_api_key | 401 | The Bearer token is present but empty |
invalid_api_key | 401 | The key does not match any active key on record |
no_api_plan | 402 | Your account has no active API plan |
Tenant errors
| Code | Status | Description |
|---|---|---|
tenant_not_found | 404 | Tenant does not exist or belongs to a different account |
tenant_limit_reached | 402 | Your plan ceiling would be exceeded by this operation |
Domain errors
| Code | Status | Description |
|---|---|---|
domain_not_found | 404 | Domain is not registered on this tenant |
domain_limit_reached | 400 | Tenant already has 12 domains (maximum) |
Mailbox errors
| Code | Status | Description |
|---|---|---|
mailbox_not_found | 404 | Mailbox does not exist on this tenant |
mailbox_limit_reached | 400 | Domain already has 3 mailboxes (maximum per domain) |
invalid_send_limit | 400 | daily_send_limit must be between 1 and 25 |
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("detail", {})
code = error.get("code")
message = error.get("message")
if code == "tenant_limit_reached":
# Handle ceiling reached
pass
elif code == "no_api_plan":
# Prompt user to purchase a plan
pass
else:
raise Exception(f"API error [{response.status_code}] {code}: {message}")
const res = await fetch("https://api.tenantcore.io/v1/tenants", {
headers: { Authorization: "Bearer tc_live_your_key" }
});
if (!res.ok) {
const { detail } = await res.json();
console.error(`[${detail.code}] ${detail.message}`);
}