Authentication

All endpoints except /signup, /login, /regions, and /errors require an API key.

Authentication Errors

HTTP 401

{
  "success": false,
  "error": "Authorization header required"
}

Response Format

Every API response includes a standard envelope with three fields: success, http_status, and code. Endpoint-specific fields are merged alongside.

Success Response

HTTP 200

{
  "success": true,
  "http_status": 200,
  "code": "ok",
  "tenant_id": "acme",
  "status": "ready"
}

Error Response

HTTP 404

{
  "success": false,
  "http_status": 404,
  "code": "not_found",
  "error": "Tenant not found: acme"
}

Standard Envelope Fields

Field	Type	Description
success	boolean	Whether the request succeeded
http_status	integer	HTTP status code (mirrors the response header)
code	string	Machine-readable status code (e.g., `ok`, `created`, `not_found`)
error	string	Human-readable error message (only present on errors)

The http_status field always matches the HTTP response status code. Use code for programmatic error handling and error for display messages.

Error Codes

All error responses use a standard code field. Use these codes for programmatic error handling instead of parsing error messages.

Code	HTTP Status	Description
ok	200	Request succeeded
created	201	Resource was created
bad_request	400	Invalid input or missing required fields
auth_required	401	Authorization header missing
unauthorized	401	Invalid API key
forbidden	403	Tier limit reached, wrong project, or operation not allowed for isolation level
not_found	404	Resource does not exist
conflict	409	Resource already exists, or operation conflicts with current state
rate_limited	429	Too many requests
internal_error	500	Server error

Example Error Responses

HTTP 409 — Conflict

{
  "success": false,
  "http_status": 409,
  "code": "conflict",
  "error": "Tenant 'acme' is in trash. Use POST /tenants/acme/restore or DELETE /tenants/acme?hard=true"
}

HTTP 403 — Forbidden

{
  "success": false,
  "http_status": 403,
  "code": "forbidden",
  "error": "PITR is only available for L2 (dedicated) tenants"
}

Rate Limits

Rate limits protect shared infrastructure and ensure fair usage. Limits are applied in layers — from IP-level DDoS protection to tier-based API quotas.

IP Rate Limiting

All requests are rate-limited by IP address before authentication. This protects against abuse and DDoS. Exceeding the limit repeatedly results in a temporary ban.

Parameter	Value	Description
Requests per second	100	Maximum requests per second from a single IP address
Ban threshold	5 violations	After 5 rate limit violations, the IP is temporarily banned
Ban duration	5 minutes	Banned IPs receive `429` for all requests during this period

Tier-Based Limits

After authentication, API requests are counted against your project's tier. Backup requests have a separate hourly limit. Dedicated tenants bypass the backup rate limit since backups run on their own server.

Limit	Window	Scope	Description
API requests	Per minute	Project	Limit varies by tier. Upgrade at tenantsdb.com/billing.
Backup requests	Per hour	Project	Limits manual backup frequency. Dedicated tenants are exempt.

Response

Rate-limited requests return HTTP 429 Too Many Requests with a Retry-After header indicating when to retry (1 second for rate limits, 300 seconds for bans).

HTTP 429

Retry-After: 1
Content-Type: application/json

{
  "success": false,
  "error": "rate limit exceeded: max 60 requests per minute"
}

IP bans apply across both the API and database proxy connections. A ban from excessive API requests also blocks proxy connections from the same IP, and vice versa.

GET /regions

List available cloud regions for dedicated tenant provisioning. This endpoint is public and does not require authentication.

Shared databases are hosted in EMEA. For region selection, create or migrate tenants to dedicated isolation.

Request

bash

curl -s https://api.tenantsdb.com/regions

Response

HTTP 200

{
  "regions": [
    {
      "zone": "eu-central",
      "label": "Europe",
      "is_default": true
    },
    {
      "zone": "ap-southeast",
      "label": "Asia Pacific"
    },
    {
      "zone": "us-east",
      "label": "US East"
    },
    {
      "zone": "us-west",
      "label": "US West"
    }
  ]
}

Use the zone value when creating dedicated tenants or migrating to a specific region. If no region is specified, the default region is used.

GET /errors

List all error codes and their HTTP status mappings. Public endpoint — no authentication required. Useful for building client libraries.

Request

bash

curl -s https://api.tenantsdb.com/errors

Response

HTTP 200

{
  "codes": {
    "ok":             { "status": 200, "description": "Request succeeded" },
    "created":        { "status": 201, "description": "Resource was created" },
    "bad_request":    { "status": 400, "description": "Invalid input or missing fields" },
    "auth_required":  { "status": 401, "description": "Authorization header missing" },
    "unauthorized":   { "status": 401, "description": "Invalid API key" },
    "forbidden":      { "status": 403, "description": "Tier limit reached or wrong project" },
    "not_found":      { "status": 404, "description": "Resource does not exist" },
    "conflict":       { "status": 409, "description": "Already exists or operation in progress" },
    "rate_limited":   { "status": 429, "description": "Too many requests" },
    "internal_error": { "status": 500, "description": "Server error" }
  }
}