Skip to main content

Troubleshooting the gateway

This guide helps diagnose and resolve common API Gateway errors, domain verification issues, and endpoint status states.

Error Response Envelope​

All Gateway API errors return a standard JSON envelope containing an error message and a unique request ID:

{
  "error": "endpoint named support-api already exists in this project",
  "request_id": "req_8f3a9c2b1d"
}

Include the request_id when submitting support inquiries.

Endpoint creation and modification errors​

an endpoint needs a name​

  • Cause: The request omitted the required name field.
  • Solution: Provide a unique lowercase endpoint name (1–40 characters).

must be lowercase letters, digits and dashes, starting with a letter​

  • Cause: Endpoint name contains invalid characters (uppercase letters, underscores, or leading numbers).
  • Solution: Use standard lowercase hyphenated names (e.g. support-api).

an endpoint named support-api already exists in this project (409)​

  • Cause: Endpoint name is already used in the active project.
  • Solution: Choose a unique name or use PATCH to update the existing endpoint.

this project already has 25 of 25 endpoints (409)​

  • Cause: Project quota ceiling reached.
  • Solution: Delete unused endpoints with platformctl gateway endpoint delete <name>.

Authentication and API key errors​

auth.mode must be one of none, jwt, apikey​

  • Cause: Invalid authentication mode specified.
  • Solution: Set auth.mode to none, jwt, or apikey.

jwt authentication needs your issuer, its key address and at least one audience​

  • Cause: Missing JWT configuration fields.
  • Solution: Provide issuer, jwks_uri (must be https://), and at least one audiences entry.

this endpoint checks API keys but has no usable key (409)​

  • Cause: Endpoint set to apikey mode, but all keys have expired or been revoked.
  • Solution: Issue a new key (platformctl gateway key issue <endpoint>) or update the authentication mode.

Custom domain errors​

add api.yourdomain.com to this project's domains first​

  • Cause: Endpoint references a custom domain that has not been claimed in the project.
  • Solution: Run platformctl gateway domain claim api.yourdomain.com before publishing.

Domain stays in pending_verification​

  • Cause: CNAME DNS record has not propagated or contains incorrect target values.
  • Solution:
    1. Verify the CNAME record points to the exact CNAME target issued by the platform.
    2. If using Cloudflare, ensure proxy status is set to DNS Only (Grey Cloud).
    3. Verify DNS propagation using dig CNAME api.yourdomain.com.

Rate limit and IP allowlist issues​

a per-key limit needs API key authentication​

  • Cause: Rate limit key set to api_key on an endpoint using none or jwt authentication.
  • Solution: Change authentication mode to apikey or set rate limit key to client_ip.

Caller receives 403 Forbidden unexpectedly​

  • Cause: Origin IP address is not included in the endpoint's --allow-cidr rules.
  • Solution: Verify the caller's public IP address and add the appropriate CIDR range to the allowlist.