Skip to content
NMC Docs
Menu
WebsiteSign in
Start here
The NMC methodWhere a lead came fromHow NMC worksFor agenciesFor business ownersFor invited clientsGlossary
Tracking
Choose a tracking sourceCall forwardingWebsite callsWebsite number poolWebsite formsGoogle Ads callsGoogle Business ProfileLocal Services AdsOther sourcesTracking numbersTextsEmails
Leads
InboxCalls, texts, and formsRepeat calls, texts, forms, and emailsStages and job valuesClosing and correctionsAI reviewContactsEmail notifications
Google Ads
Connect Google AdsWhat NMC changesChoose what Google Ads bids onUpload rulesSharing contact detailsCorrecting conversionsConversion statuses
Overview and clients
OverviewClientsClient access
Settings and billing
Business settingsSign-in and securityBillingBalance and usageAuto-reloadPaused trackingCancellation
Integrations
Google ContactsGoogle AnalyticsLocal Services AdsPermissions and dataAI assistants
Developers
API introductionLimits and errorsLists and updatesRetrying requestsForm submissionsCall recordingsTracking code
API reference
OverviewGet businessList contactsGet contactUpdate contactList leadsGet leadUpdate leadLead journeyList activitiesGet activityRecording linkList webhook endpointsAdd webhook endpointDelete webhook endpointSubmit formForm status
Webhooks
Webhook endpoints and deliveriesActivity createdActivity updatedBusiness updatedContact createdContact updatedLead createdLead updated
Help
TroubleshootingContact support

Limits and errors

Understand API rate limits, size limits, and how to handle HTTP error responses.

Authenticate every customer API request with Authorization: Bearer <key>, and send request bodies as application/json. Format all timestamps as RFC3339 strings (such as 2026-09-20T15:30:00Z). NMC rejects requests that include unknown, repeated, or empty query parameters.

Limits

Section titled “Limits”
Limit Value
Authenticated customer requests 120 per minute per business, shared across all of its API keys.
List page size Default 10; minimum 1, maximum 100.
Customer request body 64 KiB.
Webhook endpoints 3 per business by default, including stopped webhook endpoints and those created in the dashboard. Removed webhook endpoints no longer count. Contact support for a higher limit.
Dashboard webhook test and resend actions 10 per minute per business, shared across both actions.

Responses include rate-limit headers showing your limit, remaining requests, and window reset time. If you receive 429, wait for the duration in Retry-After before sending more requests. Creating extra API keys for the same business shares the same 120-per-minute allowance.

Handle errors

Section titled “Handle errors”

Failed requests return a JSON object with code and message, plus param or structured details when relevant. Branch your error-handling logic on the HTTP status and machine-readable code, and use message for display or logging context.

Status How to handle it
400 Fix the request body, query parameter (named in param), or pagination cursor before trying again.
401 Check or replace the business API key.
403 The account is on hold (account_on_hold; contact support), its plan isn’t running (plan_inactive; all requests are refused until the plan is started again in Billing), or the record is read-only.
404 Verify the resource ID and confirm it belongs to this business.
405 Switch to an HTTP method supported by the endpoint.
409 Check code. Common causes include paused tracking (tracking_paused), a reused form submission ID with different input (form_submission_conflict), an incompatible lead update (lead_status_conflict), a mismatched currency (currency_changed), a call recording still processing (recording_processing), a Google Ads conversion confirmation (google_ads_conversions_confirmation_required), or reaching the webhook endpoint limit (webhook_endpoint_limit).
413 Keep the request body within 64 KiB.
429 Wait for Retry-After before retrying.
500 / 503 Retry with exponential backoff and stop after a fixed number of attempts. Resend the identical request, keeping the same submission id on form submissions.

A write request may have succeeded on NMC’s side even if your HTTP client saw a timeout. Read Retrying requests before resending it.

Record the request ID

Section titled “Record the request ID”

Every API response includes X-Request-ID, Cache-Control: no-store, and X-Content-Type-Options: nosniff. Log X-Request-ID alongside any error code so you can share both with support when troubleshooting. Never log Authorization headers, and avoid storing request or response payloads containing contact details longer than necessary.