Error Handling

Understand the error model used across all DealSurface API endpoints.

Error response format

Error responses are JSON objects with an error field describing the issue. Some errors include additional fields for context.

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

Code	Meaning	Common causes
200	OK	Request succeeded.
400	Bad Request	Invalid parameters (e.g. non-integer product_id, missing required field, invalid enum value).
401	Unauthorized	Missing, invalid, or expired API key.
402	Payment Required	Insufficient credits for a billable operation.
403	Forbidden	Key lacks required scope, or API access is disabled for your team.
404	Not Found	Resource not found: product doesn't exist, prospect has no cached data, or company metadata not ready.
409	Conflict	Lead generation already in progress for this prospect. Wait and retry.
429	Too Many Requests	Rate limit exceeded. Check X-RateLimit-Reset header.
500	Internal Server Error	An unexpected error occurred. Details are not exposed to clients for security.
502	Bad Gateway	The backend service returned a malformed or unexpected response.
503	Service Unavailable	A downstream service is temporarily unavailable.
504	Gateway Timeout	The backend did not respond within the timeout (60 seconds for lead/outreach generation).

{
  "error": "product_id is required and must be a positive integer"
}

{
  "error": "Insufficient credits",
  "credits_remaining": 0,
  "credits_required": 10,
  "period_ends_at": "2026-04-01T00:00:00Z"
}

{
  "error": "Lead generation already in progress for this prospect"
}

{
  "error": "Rate limit exceeded. Try again in 42 seconds."
}