API reference

Errors

Every error has the same envelope, and every code has a page that explains it and how to fix it.

The envelope

The body of every 4xx and 5xx response.

{
  "error": {
    "code": "invalid_hostname",
    "message": "That is not a valid hostname.",
    "fix": "Send a hostname like careers.acme.com: no scheme, path, port, wildcard or IP address.",
    "docs": "https://apexly.dev/docs/errors/invalid_hostname"
  }
}

Field	Type	Description
`error.code`	`string`	Stable, machine-readable; branch on this.
`error.message`	`string`	What went wrong, in plain words.
`error.fix`	`string`	What to do about it, in one sentence.
`error.docs`	`string`	The page for this code, e.g. https://apexly.dev/docs/errors/invalid_hostname.
`error.request_id`	`string`	internal_error only: quote it when you contact support.

Codes

Each code links to its page: what it means, why it happens and what to do.

Code	HTTP	Message
`invalid_request`	400	The request could not be read.
`unauthorized`	401	The API key is missing, invalid or revoked.
`forbidden`	403	This credential is not allowed to do that.
`card_required`	402	Live keys need a card on file.
`live_keys_need_plan`	402	Live keys need a plan: this account is on Free.
`card_declined`	402	The card was declined.
`account_suspended`	403	The account is suspended, so changes are paused. Existing domains keep serving.
`plan_required`	403	This feature is not included in the current plan.
`not_found`	404	Nothing exists at this path, or it belongs to another app.
`idempotency_key_in_use`	409	A request with this Idempotency-Key is still being processed.
`payload_too_large`	413	The request body is larger than 100 KB.
`validation_failed`	422	The request did not pass validation.
`idempotency_key_reused`	422	This Idempotency-Key was already used with a different request.
`invalid_hostname`	422	That is not a valid hostname.
`hostname_is_apexly`	422	Hostnames under Apexly zones cannot be added.
`hostname_is_public_suffix`	422	That hostname is a public suffix, so nobody can prove control of it.
`hostname_held`	422	This hostname is held for review.
`domain_limit_reached`	422	The plan does not allow more domains.
`origin_not_allowed`	422	That origin cannot be used.
`rate_limited`	429	Too many requests.
`billing_unavailable`	503	The billing provider did not answer.
`internal_error`	500	Something went wrong on our side.

Was this helpful?

Edit this page