# Get location details API Reference Returns detailed Google Business Profile location info (hours, description, phone, website, categories, services). Use readMask to request specific fields. ## GET /v1/accounts/{accountId}/gmb-location-details **Get location details** Returns detailed Google Business Profile location info (hours, description, phone, website, categories, services). Use readMask to request specific fields. ### Parameters - **accountId** (required) in path: The Zernio account ID (from /v1/accounts) - **locationId** (optional) in query: Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs. - **readMask** (optional) in query: Comma-separated fields to return. Available: name, title, phoneNumbers, categories, storefrontAddress, websiteUri, regularHours, specialHours, serviceArea, serviceItems, profile, openInfo, metadata, moreHours. `title` and `metadata` are always included in the response so the `location` summary block can be populated, even if you omit them here. `location` is a derived response field, not a Google readMask value: passing it returns 400. ### Responses #### 200: Location details fetched successfully **Response Body:** - **success** `boolean`: No description - **accountId** `string`: No description - **locationId** `string`: No description - **location** `object,null`: Compact public-facing summary derived from Google's `metadata`. Useful for surfacing the "leave a review" URL (e.g. behind a QR code) without parsing the raw block. Always populated regardless of readMask. For unverified or new locations Google omits placeId/reviewUrl/mapsUri, so those return as null and `isVerified` is false. - **title** `string`: Business name - **regularHours** `object`: - **periods** `array[object]`: - **openDay** `string`: No description - one of: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY - **openTime** `string`: Opening time in HH:MM format - **closeDay** `string`: No description - **closeTime** `string`: No description - **specialHours** `object`: - **specialHourPeriods** `array[object]`: - **startDate** `object`: - **year** `integer`: No description - **month** `integer`: No description - **day** `integer`: No description - **endDate** `object`: - **year** `integer`: No description - **month** `integer`: No description - **day** `integer`: No description - **openTime** `string`: No description - **closeTime** `string`: No description - **closed** `boolean`: No description - **profile** `object`: - **description** `string`: Business description - **websiteUri** `string`: No description - **phoneNumbers** `object`: - **primaryPhone** `string`: No description - **additionalPhones** `array[string]`: - **categories** `object`: Business categories (returned when readMask includes 'categories') - **primaryCategory** `object`: - **name** `string`: Category resource name - **displayName** `string`: Human-readable category name - **additionalCategories** `array[object]`: - **name** `string`: No description - **displayName** `string`: No description - **serviceItems** `array[object]`: Services offered (returned when readMask includes 'serviceItems') - **structuredServiceItem** `object`: - **serviceTypeId** `string`: No description - **description** `string`: No description - **freeFormServiceItem** `object`: - **category** `string`: No description - **label** `object`: - **displayName** `string`: No description - **languageCode** `string`: No description - **price** `object`: - **currencyCode** `string`: No description - **units** `string`: No description - **nanos** `integer`: No description #### 400: Invalid request. Most commonly raised when the readMask query includes a value that is not a valid Google Business Information field (e.g. `location`, which is a response-only derived field). **Response Body:** - **error** `string`: Human-readable error message. - **type** `string`: Error class for programmatic handling. - one of: invalid_request_error, authentication_error, permission_error, not_found, rate_limit_error, platform_error, api_error - **code** `string`: Stable machine-readable error code. - **param** `string`: The request field that caused the error, when applicable. - **docUrl** `string`: Documentation page for resolving the error, when one applies. - **platform** `string`: Upstream platform (e.g. meta, google, tiktok), present when type is platform_error. - **platformError** `object`: Raw error payload from the upstream platform, passed through verbatim so integrators can read provider-specific codes. For Meta this includes error_subcode, error_user_title, and error_user_msg. - **details** `object`: Additional structured context for the error (for example field-level validation errors). What it carries depends on the endpoint and platform. **Meta ads refusals.** The ones customers hit most come back with their own `code` instead of `platform_api_error`, the field to fix in `param`, and `details.fix` ({ label, url }) pointing at the Meta page that resolves it: - `ad_account_payment_required` - `ad_account_policy_not_accepted` - `meta_security_check_required` - `meta_action_blocked` - `whatsapp_number_not_linked` - `invalid_targeting` Meta's own error stays in the message and in `platformError`. **Private replies.** `privateReplyConsumed` appears on the private-reply endpoint's 400 when the comment's single reply is already spent. `privateReplyOutcome: "unknown"` appears on its 502 when Meta answered a server error and the reply may have been delivered. **Google quota 429.** On a Google Ads or YouTube Analytics 429, `quotaExhausted: true` marks the failure as Google's own quota, not a Zernio rate limit, so you can keep calling other platforms instead of backing off everywhere. When Google names the scope, `quotaScope` is also set: - `DEVELOPER`: the shared budget (the developer token for Google Ads, the Google Cloud project for YouTube Analytics). Every account on Zernio is affected and there is nothing to change on your side. - `ACCOUNT`: your own ad account (Google Ads only). A Meta 429 carries neither field. **Zernio Google Ads burst-limit 429.** Carries `budgetScope` instead, never `quotaExhausted`. These are Zernio's own limits, applied before the call reaches Google, and both clear within a minute. They are separate axes from `quotaScope`, not the same pool named twice. - `account`: the limit of 15 requests per minute per connected Google Ads account. - `user`: the ceiling of 120 requests per minute per Zernio user across all their Google Ads accounts. **Failed Meta ad create** (`POST /v1/ads/create`, `POST /v1/ads/boost`, `POST /v1/ads/ctwa`). Carries `stage` (where it failed), `adAccountId` (on which ad account) and `createdObjects` (every object this request had already created, with what cleanup did to it). - `left_behind` objects still exist on the ad account (Meta refused the delete, typically on a held account, or the delete hit a network error). Delete them yourself or reuse them. - `unconfirmedWrite` is set when Meta answered a create with a 5xx or dropped the connection and Zernio could not confirm whether the object exists. Check that parent before creating it again. **Ineligible ad account: 422 `ad_account_unusable`.** When Meta refuses a write because the ad account's status is ineligible to manage ads (Meta subcode 2490592 or 4841021, on the write itself or on a cleanup delete), any Meta ads write answers it. That covers create, boost, CTWA, campaign / ad set / ad updates and status changes. The message names the ad account when known, links Meta's fix (https://www.facebook.com/business/help/422289316306981), lists the objects left behind and ends with Meta's original error, which also stays verbatim in `platformError`. Meta often reports the first failure under an unrelated code (e.g. 1487194 on the creative), so branch on `code`, not on `platformError`. **Missing Advertise permission: 403 `insufficient_permissions`.** When the Facebook user behind the connection's token lacks the Advertise permission on the ad account, any Meta ads write answers it. Triggers: Meta subcode 2490585, 2490591 or 4841020 on the write, or a code 200 refusal such as 1487194 whose cleanup deletes Meta refused with 2490591 or 4841020. Meta may still accept the campaign and ad set and refuse only the ad. The message names the ad account, asks for the Advertise or Manage permission on it (or a token granted `ads_management`, by reconnecting) and lists the objects left behind. It ends with Meta's `error_user_title`, `error_user_msg` and subcode; the raw error stays in `platformError`. - **stage** `string`: Meta ad create failures only. The step that failed: - `media`: image/video download or upload. - `campaign` - `adset` - `creative` - `ad`: the ad POST itself, where Meta's code 31 / 3858385 hold and 100 / 1359188 payment rejections land. - `activation`: switching the created objects on. No longer returned: a refused switch to ACTIVE now answers 201 with an `activation_failed:` warning and the objects kept PAUSED. - `other`: a read or check before any write. - one of: media, campaign, adset, creative, ad, activation, other - **adAccountId** `string`: Meta ad create failures only. The ad account the request wrote to (`act_...`). - **createdObjects** `array[object]`: Meta ad create failures only. Every object this request created before failing, in creation order. Objects you referenced (an existing campaign, ad set, creative or video) are never listed and never deleted. - **type** `string`: No description - one of: campaign, adset, creative, ad, video, image - **id** `string`: Meta object id; for `image` the image hash. - **cleanup** `string`: `deleted`: Zernio deleted it. `left_behind`: cleanup could not delete it (Meta refused the delete, or the delete hit a network error), so it still exists. `kept`: deliberately not deleted (image hashes are shared by every upload of the same file). - one of: deleted, left_behind, kept - **unconfirmedWrite** `object`: Meta ad create failures only, when Meta answered a create with a 5xx or dropped the connection and the object could not be looked up. Zernio did not retry it. - **type** `string`: No description - one of: campaign, adset, creative, ad - **parentId** `string`: Where to look for it: the ad set for an ad, the campaign for an ad set, the ad account otherwise. - **quotaExhausted** `boolean`: Google Ads and YouTube Analytics 429 only. True when the upstream Google quota is spent rather than a Zernio limit. - **quotaScope** `string`: Google Ads and YouTube Analytics 429 only, when the scope is known. DEVELOPER is the shared budget (the developer token for Google Ads, the Google Cloud project for YouTube Analytics); ACCOUNT is your ad account (Google Ads only). - one of: DEVELOPER, ACCOUNT - **budgetScope** `string`: Zernio Google Ads burst-limit 429 only (never set alongside `quotaExhausted`). `account` is the limit of 15 requests per minute per connected Google Ads account; `user` is the ceiling of 120 requests per minute per Zernio user across all their Google Ads accounts. Both clear within a minute. - one of: account, user #### 401: Unauthorized or token expired **Response Body:** - **error** `string`: Human-readable error message. - **type** `string`: Error class for programmatic handling. - one of: invalid_request_error, authentication_error, permission_error, not_found, rate_limit_error, platform_error, api_error - **code** `string`: Stable machine-readable error code. - **param** `string`: The request field that caused the error, when applicable. - **docUrl** `string`: Documentation page for resolving the error, when one applies. - **platform** `string`: Upstream platform (e.g. meta, google, tiktok), present when type is platform_error. - **platformError** `object`: Raw error payload from the upstream platform, passed through verbatim so integrators can read provider-specific codes. For Meta this includes error_subcode, error_user_title, and error_user_msg. - **details** `object`: Additional structured context for the error (for example field-level validation errors). What it carries depends on the endpoint and platform. **Meta ads refusals.** The ones customers hit most come back with their own `code` instead of `platform_api_error`, the field to fix in `param`, and `details.fix` ({ label, url }) pointing at the Meta page that resolves it: - `ad_account_payment_required` - `ad_account_policy_not_accepted` - `meta_security_check_required` - `meta_action_blocked` - `whatsapp_number_not_linked` - `invalid_targeting` Meta's own error stays in the message and in `platformError`. **Private replies.** `privateReplyConsumed` appears on the private-reply endpoint's 400 when the comment's single reply is already spent. `privateReplyOutcome: "unknown"` appears on its 502 when Meta answered a server error and the reply may have been delivered. **Google quota 429.** On a Google Ads or YouTube Analytics 429, `quotaExhausted: true` marks the failure as Google's own quota, not a Zernio rate limit, so you can keep calling other platforms instead of backing off everywhere. When Google names the scope, `quotaScope` is also set: - `DEVELOPER`: the shared budget (the developer token for Google Ads, the Google Cloud project for YouTube Analytics). Every account on Zernio is affected and there is nothing to change on your side. - `ACCOUNT`: your own ad account (Google Ads only). A Meta 429 carries neither field. **Zernio Google Ads burst-limit 429.** Carries `budgetScope` instead, never `quotaExhausted`. These are Zernio's own limits, applied before the call reaches Google, and both clear within a minute. They are separate axes from `quotaScope`, not the same pool named twice. - `account`: the limit of 15 requests per minute per connected Google Ads account. - `user`: the ceiling of 120 requests per minute per Zernio user across all their Google Ads accounts. **Failed Meta ad create** (`POST /v1/ads/create`, `POST /v1/ads/boost`, `POST /v1/ads/ctwa`). Carries `stage` (where it failed), `adAccountId` (on which ad account) and `createdObjects` (every object this request had already created, with what cleanup did to it). - `left_behind` objects still exist on the ad account (Meta refused the delete, typically on a held account, or the delete hit a network error). Delete them yourself or reuse them. - `unconfirmedWrite` is set when Meta answered a create with a 5xx or dropped the connection and Zernio could not confirm whether the object exists. Check that parent before creating it again. **Ineligible ad account: 422 `ad_account_unusable`.** When Meta refuses a write because the ad account's status is ineligible to manage ads (Meta subcode 2490592 or 4841021, on the write itself or on a cleanup delete), any Meta ads write answers it. That covers create, boost, CTWA, campaign / ad set / ad updates and status changes. The message names the ad account when known, links Meta's fix (https://www.facebook.com/business/help/422289316306981), lists the objects left behind and ends with Meta's original error, which also stays verbatim in `platformError`. Meta often reports the first failure under an unrelated code (e.g. 1487194 on the creative), so branch on `code`, not on `platformError`. **Missing Advertise permission: 403 `insufficient_permissions`.** When the Facebook user behind the connection's token lacks the Advertise permission on the ad account, any Meta ads write answers it. Triggers: Meta subcode 2490585, 2490591 or 4841020 on the write, or a code 200 refusal such as 1487194 whose cleanup deletes Meta refused with 2490591 or 4841020. Meta may still accept the campaign and ad set and refuse only the ad. The message names the ad account, asks for the Advertise or Manage permission on it (or a token granted `ads_management`, by reconnecting) and lists the objects left behind. It ends with Meta's `error_user_title`, `error_user_msg` and subcode; the raw error stays in `platformError`. - **stage** `string`: Meta ad create failures only. The step that failed: - `media`: image/video download or upload. - `campaign` - `adset` - `creative` - `ad`: the ad POST itself, where Meta's code 31 / 3858385 hold and 100 / 1359188 payment rejections land. - `activation`: switching the created objects on. No longer returned: a refused switch to ACTIVE now answers 201 with an `activation_failed:` warning and the objects kept PAUSED. - `other`: a read or check before any write. - one of: media, campaign, adset, creative, ad, activation, other - **adAccountId** `string`: Meta ad create failures only. The ad account the request wrote to (`act_...`). - **createdObjects** `array[object]`: Meta ad create failures only. Every object this request created before failing, in creation order. Objects you referenced (an existing campaign, ad set, creative or video) are never listed and never deleted. - **type** `string`: No description - one of: campaign, adset, creative, ad, video, image - **id** `string`: Meta object id; for `image` the image hash. - **cleanup** `string`: `deleted`: Zernio deleted it. `left_behind`: cleanup could not delete it (Meta refused the delete, or the delete hit a network error), so it still exists. `kept`: deliberately not deleted (image hashes are shared by every upload of the same file). - one of: deleted, left_behind, kept - **unconfirmedWrite** `object`: Meta ad create failures only, when Meta answered a create with a 5xx or dropped the connection and the object could not be looked up. Zernio did not retry it. - **type** `string`: No description - one of: campaign, adset, creative, ad - **parentId** `string`: Where to look for it: the ad set for an ad, the campaign for an ad set, the ad account otherwise. - **quotaExhausted** `boolean`: Google Ads and YouTube Analytics 429 only. True when the upstream Google quota is spent rather than a Zernio limit. - **quotaScope** `string`: Google Ads and YouTube Analytics 429 only, when the scope is known. DEVELOPER is the shared budget (the developer token for Google Ads, the Google Cloud project for YouTube Analytics); ACCOUNT is your ad account (Google Ads only). - one of: DEVELOPER, ACCOUNT - **budgetScope** `string`: Zernio Google Ads burst-limit 429 only (never set alongside `quotaExhausted`). `account` is the limit of 15 requests per minute per connected Google Ads account; `user` is the ceiling of 120 requests per minute per Zernio user across all their Google Ads accounts. Both clear within a minute. - one of: account, user #### 404: Resource not found **Response Body:** - **error** `string`: No description (example: "Not found") --- ## PUT /v1/accounts/{accountId}/gmb-location-details **Update location details** Updates Google Business Profile location details. The updateMask field is required and specifies which fields to update. This endpoint proxies Google's Business Information API locations.patch, so any valid updateMask field is supported. Common fields: regularHours, specialHours, profile.description, websiteUri, phoneNumbers, categories, serviceItems. ### Parameters - **accountId** (required) in path: The Zernio account ID (from /v1/accounts) - **locationId** (optional) in query: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs. ### Request Body - **updateMask** (required) `string`: Required. Comma-separated fields to update (e.g. 'regularHours', 'specialHours', 'profile.description', 'categories', 'serviceItems'). Any valid Google Business Information API updateMask field is supported. - **regularHours** `object`: No description - **specialHours** `object`: No description - **profile** `object`: No description - **websiteUri** `string`: No description - **phoneNumbers** `object`: No description - **categories** `object`: Primary and additional business categories. Use updateMask='categories' to update. - **serviceItems** `array`: Services offered by the business. Use updateMask='serviceItems' to update. - **title** `string`: Business name. Use updateMask='title'. - **storeCode** `string`: External store identifier, unique within the account. Use updateMask='storeCode'. - **labels** `array`: Free-form, internal-only labels for grouping (1-255 characters each). Use updateMask='labels'. - **storefrontAddress** `object`: Postal address of the storefront. Use updateMask='storefrontAddress'. Omit for service-area-only businesses. - **serviceArea** `object`: Areas the business serves. Use updateMask='serviceArea'. Full replacement: send every place you want to keep. - **openInfo** `object`: Open/closed status of the location. Use updateMask='openInfo'. - **moreHours** `array`: Additional hours for specific services (delivery, drive-through, etc.). Use updateMask='moreHours'. - **latlng** `object`: Precise coordinates. Use updateMask='latlng'. Google restricts latlng writes to approved clients, so this update may be silently ignored or rejected. - **adWordsLocationExtensions** `object`: Alternate phone shown in Google Ads location extensions. Use updateMask='adWordsLocationExtensions'. ### Responses #### 200: Location updated successfully **Response Body:** - **success** `boolean`: No description - **accountId** `string`: No description - **locationId** `string`: No description #### 400: Invalid request or missing updateMask **Response Body:** - **error** `string`: Human-readable error message. - **type** `string`: Error class for programmatic handling. - one of: invalid_request_error, authentication_error, permission_error, not_found, rate_limit_error, platform_error, api_error - **code** `string`: Stable machine-readable error code. - **param** `string`: The request field that caused the error, when applicable. - **docUrl** `string`: Documentation page for resolving the error, when one applies. - **platform** `string`: Upstream platform (e.g. meta, google, tiktok), present when type is platform_error. - **platformError** `object`: Raw error payload from the upstream platform, passed through verbatim so integrators can read provider-specific codes. For Meta this includes error_subcode, error_user_title, and error_user_msg. - **details** `object`: Additional structured context for the error (for example field-level validation errors). What it carries depends on the endpoint and platform. **Meta ads refusals.** The ones customers hit most come back with their own `code` instead of `platform_api_error`, the field to fix in `param`, and `details.fix` ({ label, url }) pointing at the Meta page that resolves it: - `ad_account_payment_required` - `ad_account_policy_not_accepted` - `meta_security_check_required` - `meta_action_blocked` - `whatsapp_number_not_linked` - `invalid_targeting` Meta's own error stays in the message and in `platformError`. **Private replies.** `privateReplyConsumed` appears on the private-reply endpoint's 400 when the comment's single reply is already spent. `privateReplyOutcome: "unknown"` appears on its 502 when Meta answered a server error and the reply may have been delivered. **Google quota 429.** On a Google Ads or YouTube Analytics 429, `quotaExhausted: true` marks the failure as Google's own quota, not a Zernio rate limit, so you can keep calling other platforms instead of backing off everywhere. When Google names the scope, `quotaScope` is also set: - `DEVELOPER`: the shared budget (the developer token for Google Ads, the Google Cloud project for YouTube Analytics). Every account on Zernio is affected and there is nothing to change on your side. - `ACCOUNT`: your own ad account (Google Ads only). A Meta 429 carries neither field. **Zernio Google Ads burst-limit 429.** Carries `budgetScope` instead, never `quotaExhausted`. These are Zernio's own limits, applied before the call reaches Google, and both clear within a minute. They are separate axes from `quotaScope`, not the same pool named twice. - `account`: the limit of 15 requests per minute per connected Google Ads account. - `user`: the ceiling of 120 requests per minute per Zernio user across all their Google Ads accounts. **Failed Meta ad create** (`POST /v1/ads/create`, `POST /v1/ads/boost`, `POST /v1/ads/ctwa`). Carries `stage` (where it failed), `adAccountId` (on which ad account) and `createdObjects` (every object this request had already created, with what cleanup did to it). - `left_behind` objects still exist on the ad account (Meta refused the delete, typically on a held account, or the delete hit a network error). Delete them yourself or reuse them. - `unconfirmedWrite` is set when Meta answered a create with a 5xx or dropped the connection and Zernio could not confirm whether the object exists. Check that parent before creating it again. **Ineligible ad account: 422 `ad_account_unusable`.** When Meta refuses a write because the ad account's status is ineligible to manage ads (Meta subcode 2490592 or 4841021, on the write itself or on a cleanup delete), any Meta ads write answers it. That covers create, boost, CTWA, campaign / ad set / ad updates and status changes. The message names the ad account when known, links Meta's fix (https://www.facebook.com/business/help/422289316306981), lists the objects left behind and ends with Meta's original error, which also stays verbatim in `platformError`. Meta often reports the first failure under an unrelated code (e.g. 1487194 on the creative), so branch on `code`, not on `platformError`. **Missing Advertise permission: 403 `insufficient_permissions`.** When the Facebook user behind the connection's token lacks the Advertise permission on the ad account, any Meta ads write answers it. Triggers: Meta subcode 2490585, 2490591 or 4841020 on the write, or a code 200 refusal such as 1487194 whose cleanup deletes Meta refused with 2490591 or 4841020. Meta may still accept the campaign and ad set and refuse only the ad. The message names the ad account, asks for the Advertise or Manage permission on it (or a token granted `ads_management`, by reconnecting) and lists the objects left behind. It ends with Meta's `error_user_title`, `error_user_msg` and subcode; the raw error stays in `platformError`. - **stage** `string`: Meta ad create failures only. The step that failed: - `media`: image/video download or upload. - `campaign` - `adset` - `creative` - `ad`: the ad POST itself, where Meta's code 31 / 3858385 hold and 100 / 1359188 payment rejections land. - `activation`: switching the created objects on. No longer returned: a refused switch to ACTIVE now answers 201 with an `activation_failed:` warning and the objects kept PAUSED. - `other`: a read or check before any write. - one of: media, campaign, adset, creative, ad, activation, other - **adAccountId** `string`: Meta ad create failures only. The ad account the request wrote to (`act_...`). - **createdObjects** `array[object]`: Meta ad create failures only. Every object this request created before failing, in creation order. Objects you referenced (an existing campaign, ad set, creative or video) are never listed and never deleted. - **type** `string`: No description - one of: campaign, adset, creative, ad, video, image - **id** `string`: Meta object id; for `image` the image hash. - **cleanup** `string`: `deleted`: Zernio deleted it. `left_behind`: cleanup could not delete it (Meta refused the delete, or the delete hit a network error), so it still exists. `kept`: deliberately not deleted (image hashes are shared by every upload of the same file). - one of: deleted, left_behind, kept - **unconfirmedWrite** `object`: Meta ad create failures only, when Meta answered a create with a 5xx or dropped the connection and the object could not be looked up. Zernio did not retry it. - **type** `string`: No description - one of: campaign, adset, creative, ad - **parentId** `string`: Where to look for it: the ad set for an ad, the campaign for an ad set, the ad account otherwise. - **quotaExhausted** `boolean`: Google Ads and YouTube Analytics 429 only. True when the upstream Google quota is spent rather than a Zernio limit. - **quotaScope** `string`: Google Ads and YouTube Analytics 429 only, when the scope is known. DEVELOPER is the shared budget (the developer token for Google Ads, the Google Cloud project for YouTube Analytics); ACCOUNT is your ad account (Google Ads only). - one of: DEVELOPER, ACCOUNT - **budgetScope** `string`: Zernio Google Ads burst-limit 429 only (never set alongside `quotaExhausted`). `account` is the limit of 15 requests per minute per connected Google Ads account; `user` is the ceiling of 120 requests per minute per Zernio user across all their Google Ads accounts. Both clear within a minute. - one of: account, user #### 401: Unauthorized or token expired **Response Body:** - **error** `string`: Human-readable error message. - **type** `string`: Error class for programmatic handling. - one of: invalid_request_error, authentication_error, permission_error, not_found, rate_limit_error, platform_error, api_error - **code** `string`: Stable machine-readable error code. - **param** `string`: The request field that caused the error, when applicable. - **docUrl** `string`: Documentation page for resolving the error, when one applies. - **platform** `string`: Upstream platform (e.g. meta, google, tiktok), present when type is platform_error. - **platformError** `object`: Raw error payload from the upstream platform, passed through verbatim so integrators can read provider-specific codes. For Meta this includes error_subcode, error_user_title, and error_user_msg. - **details** `object`: Additional structured context for the error (for example field-level validation errors). What it carries depends on the endpoint and platform. **Meta ads refusals.** The ones customers hit most come back with their own `code` instead of `platform_api_error`, the field to fix in `param`, and `details.fix` ({ label, url }) pointing at the Meta page that resolves it: - `ad_account_payment_required` - `ad_account_policy_not_accepted` - `meta_security_check_required` - `meta_action_blocked` - `whatsapp_number_not_linked` - `invalid_targeting` Meta's own error stays in the message and in `platformError`. **Private replies.** `privateReplyConsumed` appears on the private-reply endpoint's 400 when the comment's single reply is already spent. `privateReplyOutcome: "unknown"` appears on its 502 when Meta answered a server error and the reply may have been delivered. **Google quota 429.** On a Google Ads or YouTube Analytics 429, `quotaExhausted: true` marks the failure as Google's own quota, not a Zernio rate limit, so you can keep calling other platforms instead of backing off everywhere. When Google names the scope, `quotaScope` is also set: - `DEVELOPER`: the shared budget (the developer token for Google Ads, the Google Cloud project for YouTube Analytics). Every account on Zernio is affected and there is nothing to change on your side. - `ACCOUNT`: your own ad account (Google Ads only). A Meta 429 carries neither field. **Zernio Google Ads burst-limit 429.** Carries `budgetScope` instead, never `quotaExhausted`. These are Zernio's own limits, applied before the call reaches Google, and both clear within a minute. They are separate axes from `quotaScope`, not the same pool named twice. - `account`: the limit of 15 requests per minute per connected Google Ads account. - `user`: the ceiling of 120 requests per minute per Zernio user across all their Google Ads accounts. **Failed Meta ad create** (`POST /v1/ads/create`, `POST /v1/ads/boost`, `POST /v1/ads/ctwa`). Carries `stage` (where it failed), `adAccountId` (on which ad account) and `createdObjects` (every object this request had already created, with what cleanup did to it). - `left_behind` objects still exist on the ad account (Meta refused the delete, typically on a held account, or the delete hit a network error). Delete them yourself or reuse them. - `unconfirmedWrite` is set when Meta answered a create with a 5xx or dropped the connection and Zernio could not confirm whether the object exists. Check that parent before creating it again. **Ineligible ad account: 422 `ad_account_unusable`.** When Meta refuses a write because the ad account's status is ineligible to manage ads (Meta subcode 2490592 or 4841021, on the write itself or on a cleanup delete), any Meta ads write answers it. That covers create, boost, CTWA, campaign / ad set / ad updates and status changes. The message names the ad account when known, links Meta's fix (https://www.facebook.com/business/help/422289316306981), lists the objects left behind and ends with Meta's original error, which also stays verbatim in `platformError`. Meta often reports the first failure under an unrelated code (e.g. 1487194 on the creative), so branch on `code`, not on `platformError`. **Missing Advertise permission: 403 `insufficient_permissions`.** When the Facebook user behind the connection's token lacks the Advertise permission on the ad account, any Meta ads write answers it. Triggers: Meta subcode 2490585, 2490591 or 4841020 on the write, or a code 200 refusal such as 1487194 whose cleanup deletes Meta refused with 2490591 or 4841020. Meta may still accept the campaign and ad set and refuse only the ad. The message names the ad account, asks for the Advertise or Manage permission on it (or a token granted `ads_management`, by reconnecting) and lists the objects left behind. It ends with Meta's `error_user_title`, `error_user_msg` and subcode; the raw error stays in `platformError`. - **stage** `string`: Meta ad create failures only. The step that failed: - `media`: image/video download or upload. - `campaign` - `adset` - `creative` - `ad`: the ad POST itself, where Meta's code 31 / 3858385 hold and 100 / 1359188 payment rejections land. - `activation`: switching the created objects on. No longer returned: a refused switch to ACTIVE now answers 201 with an `activation_failed:` warning and the objects kept PAUSED. - `other`: a read or check before any write. - one of: media, campaign, adset, creative, ad, activation, other - **adAccountId** `string`: Meta ad create failures only. The ad account the request wrote to (`act_...`). - **createdObjects** `array[object]`: Meta ad create failures only. Every object this request created before failing, in creation order. Objects you referenced (an existing campaign, ad set, creative or video) are never listed and never deleted. - **type** `string`: No description - one of: campaign, adset, creative, ad, video, image - **id** `string`: Meta object id; for `image` the image hash. - **cleanup** `string`: `deleted`: Zernio deleted it. `left_behind`: cleanup could not delete it (Meta refused the delete, or the delete hit a network error), so it still exists. `kept`: deliberately not deleted (image hashes are shared by every upload of the same file). - one of: deleted, left_behind, kept - **unconfirmedWrite** `object`: Meta ad create failures only, when Meta answered a create with a 5xx or dropped the connection and the object could not be looked up. Zernio did not retry it. - **type** `string`: No description - one of: campaign, adset, creative, ad - **parentId** `string`: Where to look for it: the ad set for an ad, the campaign for an ad set, the ad account otherwise. - **quotaExhausted** `boolean`: Google Ads and YouTube Analytics 429 only. True when the upstream Google quota is spent rather than a Zernio limit. - **quotaScope** `string`: Google Ads and YouTube Analytics 429 only, when the scope is known. DEVELOPER is the shared budget (the developer token for Google Ads, the Google Cloud project for YouTube Analytics); ACCOUNT is your ad account (Google Ads only). - one of: DEVELOPER, ACCOUNT - **budgetScope** `string`: Zernio Google Ads burst-limit 429 only (never set alongside `quotaExhausted`). `account` is the limit of 15 requests per minute per connected Google Ads account; `user` is the ceiling of 120 requests per minute per Zernio user across all their Google Ads accounts. Both clear within a minute. - one of: account, user #### 404: Resource not found **Response Body:** - **error** `string`: No description (example: "Not found") --- # Related Schema Definitions ## ErrorResponse Canonical error envelope. `error` is the human-readable message; `type`, `code`, `param`, `platform`, and `platformError` are top-level siblings for programmatic handling. For upstream platform failures (`type: platform_error`), `platformError` carries the provider's raw payload verbatim (for Meta: `error_subcode`, `error_user_title`, `error_user_msg`). ### Properties - **error** `string`: Human-readable error message. - **type** `string`: Error class for programmatic handling. - one of: invalid_request_error, authentication_error, permission_error, not_found, rate_limit_error, platform_error, api_error - **code** `string`: Stable machine-readable error code. - **param** `string`: The request field that caused the error, when applicable. - **docUrl** `string`: Documentation page for resolving the error, when one applies. - **platform** `string`: Upstream platform (e.g. meta, google, tiktok), present when type is platform_error. - **platformError** `object`: Raw error payload from the upstream platform, passed through verbatim so integrators can read provider-specific codes. For Meta this includes error_subcode, error_user_title, and error_user_msg. - **details** `object`: Additional structured context for the error (for example field-level validation errors). What it carries depends on the endpoint and platform. **Meta ads refusals.** The ones customers hit most come back with their own `code` instead of `platform_api_error`, the field to fix in `param`, and `details.fix` ({ label, url }) pointing at the Meta page that resolves it: - `ad_account_payment_required` - `ad_account_policy_not_accepted` - `meta_security_check_required` - `meta_action_blocked` - `whatsapp_number_not_linked` - `invalid_targeting` Meta's own error stays in the message and in `platformError`. **Private replies.** `privateReplyConsumed` appears on the private-reply endpoint's 400 when the comment's single reply is already spent. `privateReplyOutcome: "unknown"` appears on its 502 when Meta answered a server error and the reply may have been delivered. **Google quota 429.** On a Google Ads or YouTube Analytics 429, `quotaExhausted: true` marks the failure as Google's own quota, not a Zernio rate limit, so you can keep calling other platforms instead of backing off everywhere. When Google names the scope, `quotaScope` is also set: - `DEVELOPER`: the shared budget (the developer token for Google Ads, the Google Cloud project for YouTube Analytics). Every account on Zernio is affected and there is nothing to change on your side. - `ACCOUNT`: your own ad account (Google Ads only). A Meta 429 carries neither field. **Zernio Google Ads burst-limit 429.** Carries `budgetScope` instead, never `quotaExhausted`. These are Zernio's own limits, applied before the call reaches Google, and both clear within a minute. They are separate axes from `quotaScope`, not the same pool named twice. - `account`: the limit of 15 requests per minute per connected Google Ads account. - `user`: the ceiling of 120 requests per minute per Zernio user across all their Google Ads accounts. **Failed Meta ad create** (`POST /v1/ads/create`, `POST /v1/ads/boost`, `POST /v1/ads/ctwa`). Carries `stage` (where it failed), `adAccountId` (on which ad account) and `createdObjects` (every object this request had already created, with what cleanup did to it). - `left_behind` objects still exist on the ad account (Meta refused the delete, typically on a held account, or the delete hit a network error). Delete them yourself or reuse them. - `unconfirmedWrite` is set when Meta answered a create with a 5xx or dropped the connection and Zernio could not confirm whether the object exists. Check that parent before creating it again. **Ineligible ad account: 422 `ad_account_unusable`.** When Meta refuses a write because the ad account's status is ineligible to manage ads (Meta subcode 2490592 or 4841021, on the write itself or on a cleanup delete), any Meta ads write answers it. That covers create, boost, CTWA, campaign / ad set / ad updates and status changes. The message names the ad account when known, links Meta's fix (https://www.facebook.com/business/help/422289316306981), lists the objects left behind and ends with Meta's original error, which also stays verbatim in `platformError`. Meta often reports the first failure under an unrelated code (e.g. 1487194 on the creative), so branch on `code`, not on `platformError`. **Missing Advertise permission: 403 `insufficient_permissions`.** When the Facebook user behind the connection's token lacks the Advertise permission on the ad account, any Meta ads write answers it. Triggers: Meta subcode 2490585, 2490591 or 4841020 on the write, or a code 200 refusal such as 1487194 whose cleanup deletes Meta refused with 2490591 or 4841020. Meta may still accept the campaign and ad set and refuse only the ad. The message names the ad account, asks for the Advertise or Manage permission on it (or a token granted `ads_management`, by reconnecting) and lists the objects left behind. It ends with Meta's `error_user_title`, `error_user_msg` and subcode; the raw error stays in `platformError`. - **stage** `string`: Meta ad create failures only. The step that failed: - `media`: image/video download or upload. - `campaign` - `adset` - `creative` - `ad`: the ad POST itself, where Meta's code 31 / 3858385 hold and 100 / 1359188 payment rejections land. - `activation`: switching the created objects on. No longer returned: a refused switch to ACTIVE now answers 201 with an `activation_failed:` warning and the objects kept PAUSED. - `other`: a read or check before any write. - one of: media, campaign, adset, creative, ad, activation, other - **adAccountId** `string`: Meta ad create failures only. The ad account the request wrote to (`act_...`). - **createdObjects** `array`: Meta ad create failures only. Every object this request created before failing, in creation order. Objects you referenced (an existing campaign, ad set, creative or video) are never listed and never deleted. - **unconfirmedWrite** `object`: Meta ad create failures only, when Meta answered a create with a 5xx or dropped the connection and the object could not be looked up. Zernio did not retry it. - **quotaExhausted** `boolean`: Google Ads and YouTube Analytics 429 only. True when the upstream Google quota is spent rather than a Zernio limit. - **quotaScope** `string`: Google Ads and YouTube Analytics 429 only, when the scope is known. DEVELOPER is the shared budget (the developer token for Google Ads, the Google Cloud project for YouTube Analytics); ACCOUNT is your ad account (Google Ads only). - one of: DEVELOPER, ACCOUNT - **budgetScope** `string`: Zernio Google Ads burst-limit 429 only (never set alongside `quotaExhausted`). `account` is the limit of 15 requests per minute per connected Google Ads account; `user` is the ceiling of 120 requests per minute per Zernio user across all their Google Ads accounts. Both clear within a minute. - one of: account, user