Misar.io Documentation

Error response format

All MisarReach API errors return a JSON object with an error field:

{ "error": "Human-readable error message" }

Some endpoints return additional fields alongside error:

{
  "error": "Free-plan monthly search limit reached (25/mo). Upgrade or top up credits to keep searching.",
  "balance": 0,
  "freeRemaining": 0,
  "upgrade": true
}

Validation errors from Zod include a nested error object with field-level detail:

{
  "error": {
    "fieldErrors": { "query": ["String must contain at least 2 character(s)"] },
    "formErrors": []
  }
}

HTTP status codes

Code	Meaning
`200`	Success
`201`	Created
`202`	Accepted (async job started — poll for results)
`400`	Bad request — missing required field, invalid JSON, or malformed UUID
`401`	Unauthorized — missing or invalid API key, or expired session
`403`	Forbidden — valid credentials but insufficient scope for this operation
`404`	Not found — resource does not exist or does not belong to the authenticated user
`422`	Unprocessable entity — request parsed but failed validation
`429`	Credit limit reached — wallet balance exhausted or free-plan monthly allowance used
`500`	Internal server error
`502`	Upstream service error (e.g., Hunter.io API unreachable)

Common errors

`401 Unauthorized`

{ "error": "Unauthorized" }

Cause: The Authorization header is missing, the API key is invalid, or the session has expired.

Fix: Generate a new API key from Dashboard → Settings → API Keys and verify the Authorization: Bearer msr_your_key_here header is present on every request.

`403 Forbidden — insufficient scope`

{ "error": "Forbidden" }

Cause: The API key does not have the required scope for this endpoint (e.g., using a leads:read key on a leads:write endpoint).

Fix: Generate a new API key with the required scopes.

`429 Credit limit`

{
  "error": "Verification credit limit reached",
  "upgrade": true
}

Cause: Your verification, AI, or search credit balance is exhausted.

Fix: Top up credits from Dashboard → Billing or upgrade your plan. Free-plan accounts receive 25 lead searches per month before credits are required.

`429 Free plan monthly search limit`

{
  "error": "Free-plan monthly search limit reached (25/mo). Upgrade or top up credits to keep searching.",
  "balance": 0,
  "freeRemaining": 0,
  "upgrade": true
}

Cause: You have used all 25 free searches for the current calendar month.

Fix: Top up credits or upgrade your plan to continue searching.

`400 Invalid returnUrl` (SSO endpoints)

{ "error": "Invalid returnUrl" }

Cause: The returnUrl does not match a registered domain or path in the SSO platform registry.

`404 Deal not found`

{ "error": "Deal not found" }

Cause: The deal UUID does not exist, or it belongs to a different user account.

`502 Upstream error`

{ "error": "Failed to create list — check HUNTER_API_KEY" }

Cause: The Hunter.io API was unreachable or rejected the request. This is a transient error.

Fix: Retry after a short delay. If the error persists, verify your Hunter.io API key configuration or check status.misar.io.

Retries

MisarReach does not automatically retry failed requests. For 5xx errors and 502 upstream errors, implement exponential backoff on the client side.

Recommended retry strategy for async jobs:

On POST /api/lead-finder/search → poll GET /api/lead-finder/jobs/:jobId every 2 seconds
Stop polling when status is "completed" or "failed"
Maximum poll time: 120 seconds before treating as a timeout

Status page

Monitor MisarReach service health at status.misar.io.

Errors

On this page