Reference

Errors

Every error of the REST API is an application/problem+json document (RFC 9457) with a stable code to switch on and a detail to show. 49 codes, what each means and what to do.

Format

403 · application/problem+json

{
  "type": "https://app.apogee.ad/docs/api#errors-insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This key has no \"launch\" scope: create a key with it in app.apogee.ad → API & MCP.",
  "code": "insufficient_scope",
  "request_id": "req_Zm9yIHRoZSBkb2NzIG9ubHk",
  "required_scope": "launch"
}

Field	What it holds
`type`	A URL naming the error, built from its `code`.
`title`	A short title of the code.
`status`	The HTTP status, repeated.
`detail`	What happened, in a sentence written for a person: show it.
`code`	The stable code to switch on (below). New codes may appear within v1; existing ones never change.
`request_id`	This request's id, also in the `X-Request-Id` header: give it to support.
`errors`	`validation_failed`: one entry per refused field, with `param` (its path), `code` and `message`.
`missing`	`missing_answers`: the open questions of a launch plan, each with `id`, `question`, `needs` and `answer_with`.
`required_scope`	`insufficient_scope`: the scope the key needs.
`feature, required_plan, current_plan`	`upgrade_required`: the feature, the plan that includes it, the account's plan.
`retry_after`	Seconds to wait (also in `Retry-After`).
`buy_url`	`credits_exhausted`: the page of the Apogee app that sells credit packs.
`meta`	Meta's own error, when Meta refused: `{ code }`.

A 401 also carries WWW-Authenticate; a 429, Retry-After.

Error codes

400 Bad request

Code	Meaning and what to do
`idempotency_key_required`	Idempotency-Key header required. This write needs an `Idempotency-Key` header: 1 to 255 visible ASCII characters, for example a UUID. Reuse the same key when you retry the same request.
`not_supported`	Not supported. This combination is not supported (yet). `detail` says what is not.
`request_refused`	Request refused. Apogee refused the request for the reason in `detail`, the same message the app shows. Fix what it says before you retry: the same request is refused the same way.
`validation_failed`	Validation failed. The request does not match what the route accepts. `errors` lists each refused field (`param`), with a code and a message. Unknown fields are refused too: send only the documented ones.

401 Unauthorized

Code	Meaning and what to do
`invalid_api_key`	Invalid API key. The `Authorization` header is missing, or the key is unknown, revoked or expired: Apogee answers the same for all three. Send `Authorization: Bearer apk_…` with an active key from Settings → Connections → API. OAuth tokens (`apo_at_…`) work on the MCP server only.

402 Payment required

Code	Meaning and what to do
`cost_ceiling_reached`	The account's monthly safety limit is reached. A monthly safety limit of the account was reached. Write to hello@apogee.ad with the `request_id`.
`credits_exhausted`	This month's API credits are used. This month's credits and every credit pack are used. Requests that cost credits are refused until the 1st of next month (UTC); reads go on within their daily cap. `buy_url` opens the page that sells credit packs.
`free_daily_limit_reached`	The free plan's MCP credits of the day are used. A free Apogee account used its MCP credits of the day. They come back at midnight UTC; the message says in how many hours and links to the plans, to subscribe and keep going. Calls that cost nothing, such as who am I or following a job, still answer.
`member_cap_reached`	The member's monthly credits are used. The workspace owner set a monthly credit cap for this member, and it is used. Ask the owner to raise it (Workspace → Usage). Reads go on within their daily cap.
`payment_failed`	The account's last payment failed. The account's last payment failed, for example the first charge at the end of a 7-day trial: the features of its plan are paused. Update the payment method in Settings → Billing, then retry.
`plan_required`	A paid plan is required. This needs a paid Apogee plan. Subscribe in the app, then retry.

403 Forbidden

Code	Meaning and what to do
`account_not_connected`	Ad account not connected. The TikTok or Snapchat ad account is not one this Apogee account connected. Connect it in the app (Settings → Workspace → Ad accounts), then find its id with `GET /ad-accounts?platform=…`.
`forbidden`	Forbidden. The request is not allowed for this account. Check that the ad account, page or object belongs to the Apogee account of the key.
`insufficient_scope`	Insufficient scope. The key lacks the scope this route needs: `required_scope` names it. Create a key with that scope (a key's scopes are chosen when it is created).
`meta_permission_denied`	Meta refused the access. Meta refused the access with this Apogee account's Facebook connection (no role on the ad account, the page or the business). Fix the access in Meta Business Settings, then log in to Apogee again.
`platform_permission_denied`	TikTok or Snapchat refused the access. TikTok or Snapchat refused the access: a role or a permission is missing on the ad account. Fix it on the platform, then reconnect it in the app.
`upgrade_required`	The Apogee plan does not include this feature. The account's plan does not include this feature: `feature` names it, `required_plan` is the plan that includes it, `current_plan` the account's. The key works again as soon as the plan includes it.

404 Not found

Code	Meaning and what to do
`not_found`	Not found. No such object, or not one of this account's. A wrong path answers it too: check the reference.

405 Method not allowed

Code	Meaning and what to do
`method_not_allowed`	Method not allowed. The path exists with another HTTP method: the `Allow` header lists them.

409 Conflict

Code	Meaning and what to do
`action_already_ran`	Action already ran. This action already ran: an action runs once. Prepare a new one to do it again.
`idempotency_in_progress`	A request with this Idempotency-Key is in progress. A request with this `Idempotency-Key` is still running. Retry the same request after `Retry-After` seconds: you get its answer.
`plan_already_launched`	Plan already launched. This launch plan already ran: a plan launches once. Prepare a new plan to launch again.
`same_error_again`	The last launches failed with the same error. MCP only: the last launches on this ad account failed with the same error. Fix its cause first, then launch with `previous_error_fixed: true`.
`too_many_keys`	Too many API keys. The account has 10 active API keys, the most it can have. Revoke one in Settings → Connections → API first.

410 Gone

Code	Meaning and what to do
`action_expired`	Action expired. The action was prepared more than 24 hours ago. Prepare it again.
`plan_expired`	Plan expired. The launch plan was prepared more than 24 hours ago. Prepare it again: the recap is read again too.

412 Precondition failed

Code	Meaning and what to do
`drive_not_connected`	Google Drive connection needed. Google Drive is not connected to this Apogee account, or the folder is not shared with it. Connect Drive in the app, or share the folder as "Anyone with the link".
`meta_not_connected`	Facebook connection needed. The Facebook connection of this Apogee account is missing or expired: log in to app.apogee.ad again. It never means the API key is wrong (that is a 401).
`platform_not_connected`	TikTok or Snapchat connection needed. The TikTok or Snapchat connection was revoked or expired: reconnect it in the app.

413 Payload too large

Code	Meaning and what to do
`payload_too_large`	Payload too large. The JSON body is larger than 2 MB. Send files with `POST /uploads`, never inside a body.

422 Unprocessable content

Code	Meaning and what to do
`budget_above_cap`	Budget above the safety cap. The daily budget is above Apogee's safety cap (500 a day in the ad account's currency). Lower it, or change the budget in the app.
`idempotency_key_reused`	Idempotency-Key reused with another request. This `Idempotency-Key` was already used with another request (another path or body). Use a new key for a new request.
`launch_refused`	Launch refused. Apogee's checks or the platform's pre-flight refused the launch: `detail` says why. Nothing was created.
`missing_answers`	The launch plan has open questions. The launch plan still has open questions: `missing` lists each one, with what it needs and how to answer it. Nothing was saved: answer them and send the whole plan again.

429 Too many requests

Code	Meaning and what to do
`daily_read_cap`	Daily reads used. The account made three times its daily free reads today. Reads are refused until midnight UTC.
`meta_rate_limited`	Meta is rate limiting this account. Meta is throttling the ad account, or the whole Facebook connection. Apogee stops calling Meta for it for 2 minutes instead of retrying: wait `Retry-After` seconds.
`platform_rate_limited`	TikTok or Snapchat is rate limiting this account. TikTok or Snapchat is throttling the account. Wait `Retry-After` seconds.
`quota_exceeded`	Daily quota reached. A 24-hour quota is reached: the units of one API key or assistant connection, the launches and transfers of one ad account, or the comment idea runs of the account. `Retry-After` says when it frees up.
`rate_limited`	Too many requests. Too many requests in the window: the rate limits of the plan, or the Meta, TikTok or Snapchat budget of the account. Wait `Retry-After` seconds.

500 Internal server error

Code	Meaning and what to do
`internal_error`	Internal error. Apogee failed on its side. It was recorded: retry later, and give the `request_id` to support if it keeps failing.

502 Bad gateway

Code	Meaning and what to do
`drive_error`	Google Drive error. Google Drive did not answer properly. Retry later.
`launch_failed`	Launch failed. The launch failed on the platform: `detail` says why. Check the ad account in Ads Manager before you launch again.
`meta_error`	Meta refused the request. Meta refused the request: `detail` gives Meta's message and `meta.code` its error code.
`platform_error`	TikTok or Snapchat refused the request. TikTok or Snapchat refused the request: `detail` gives their message.
`upstream_error`	Upstream error. A service Apogee relies on failed. Retry later; give the `request_id` to support if it keeps failing.

503 Service unavailable

Code	Meaning and what to do
`ai_paused`	AI features paused until next month. Apogee's AI features are paused for the API and the MCP until the 1st of next month. Everything else works, and the app keeps them.
`feature_not_ready`	This feature is not available yet. This feature is not available on this server yet.
`service_disabled`	Paused for maintenance. The API and the MCP are paused for maintenance: everything, or only what writes (reads go on). Retry later; the Apogee app keeps working.

504 Gateway timeout

Code	Meaning and what to do
`meta_timeout`	Meta did not answer in time. Meta did not answer in time. Retry; before you repeat a write, check Ads Manager that it did not go through.

Each operation's page lists the statuses it can answer.

On the MCP server

A tool that refuses or fails answers a normal result with isError: true and the reason in words: the same refusals as the REST API (a missing scope, credits used, a daily cap, an open launch question…), written for the assistant to read and fix its call. It costs nothing.
A launch question still open: prepare_launch answers ready: false with what to ask; the assistant asks you, then calls it again.
HTTP errors concern the connection itself: 401 (no valid credential, with the OAuth discovery header), 403 (the plan does not include the MCP server, as a JSON-RPC error), 429 (too many requests), 405 (GET or DELETE on the server).

Retrying

Retry after waiting: 429 after Retry-After; 409 idempotency_in_progress with the same Idempotency-Key; 500, 502, 503 and 504 a little later.
Fix before retrying: every other 4xx is answered the same way until its cause changes (detail says what).
Writes: retry them with the same Idempotency-Key, never without: you get the first answer instead of a second import, plan or action. After a timeout on a launch or a change, check the platform before repeating it without a key.