Skip to main content
The NearIQ API uses standard HTTP status codes to signal the outcome of every request. All error responses return a JSON body with a single error field containing a human-readable message.

​
Error response format

Every non-2xx response follows this shape: 
{
  "error": "A description of what went wrong."
}
Some validation errors include additional fields alongside error to help you fix the problem. For example, submitting an unknown webhook event returns: 
{
  "error": "Unknown events: competitor.unknown_event",
  "allowedEvents": [
    "competitor.rating_change",
    "competitor.review_surge",
    "competitor.hours_change",
    "competitor.website_change",
    "competitor.new_competitor",
    "business.rating_change",
    "business.review_surge",
    "alert.created"
  ]
}

​
HTTP status codes

StatusMeaningCommon causes
200 OKSuccess—
201 CreatedResource createdWebhook endpoint registered
204 No ContentSuccess, no bodyWebhook deleted
400 Bad RequestInvalid parametersMissing required field, invalid JSON body, bad URL
401 UnauthorizedAuthentication failedMissing, malformed, or revoked API key
404 Not FoundResource not foundCompetitor ID doesn’t exist or doesn’t belong to your account
422 Unprocessable EntityValidation errorWebhook limit of 10 reached
500 Internal Server ErrorServer errorUnexpected server-side failure

​
400 Bad Request

You sent a request the server could not understand. This typically means a required parameter is absent or has the wrong type. 
{ "error": "`url` is required and must be a string." }

​
401 Unauthorized

Your API key is missing or invalid. See Authentication for the correct header format. 
{ "error": "Invalid or missing API key. Pass your key via X-NearIQ-Key header." }

​
404 Not Found

The requested resource doesn’t exist, or it exists but belongs to a different account. NearIQ returns 404 (not 403) in both cases to avoid leaking information about other accounts. 
{ "error": "Competitor not found or does not belong to your account." }

​
422 Unprocessable Entity

Your request was well-formed but couldn’t be completed due to a business rule. The most common example is exceeding the 10-webhook limit per account. 
{ "error": "Maximum of 10 webhook endpoints allowed per account." }

​
500 Internal Server Error

Something went wrong on our end. These are rare — if you see a 500 on a request that was previously working, check the NearIQ status page or contact support.

​
Rate limiting

The NearIQ API enforces per-account rate limits. When you exceed the limit, requests return 429 Too Many Requests. The response includes a Retry-After header indicating how many seconds to wait before retrying.

​
Handling errors in code

import { NearIQ, NearIQError } from '@neariq/sdk'

const client = new NearIQ({ apiKey: process.env.NEARIQ_API_KEY! })

try {
  const biz = await client.me.get()
  console.log(biz.name)
} catch (err) {
  if (err instanceof Error && 'status' in err) {
    const e = err as NearIQError
    console.error(`NearIQ error ${e.status}: ${e.message}`)
    // e.body contains the full JSON response
  } else {
    throw err
  }
}