Error Handling

Error response format

When a request fails, the API returns a JSON error body:

{
  "error": "Deal room not found",
  "code": "not_found",
  "details": {}
}

error — Human-readable error message (safe to display to users)
code — Machine-readable error code (use this for programmatic handling)
details — Optional structured data with additional context

Error codes

Client errors (4xx)

Code	HTTP Status	Description	What to do
`bad_request`	400	Generic bad request	Check your request format
`validation_error`	400	Invalid query parameters	Check `details` for specific field errors
`unauthorized`	401	Missing or invalid API key	Verify your API key is correct and not revoked
`payment_required`	402	Plan doesn't include API access	Upgrade to the Scale plan
`forbidden`	403	Insufficient permissions	Check your API key scopes
`not_found`	404	Resource doesn't exist	Verify the deal room ID exists and belongs to your team
`conflict`	409	Resource conflict	The resource already exists or has a duplicate identifier
`gone`	410	Resource expired or removed	The resource is no longer available
`payload_too_large`	413	Request body too large	Reduce the payload size
`unsupported_media_type`	415	Invalid content type	Use `application/json`
`rate_limit`	429	Too many requests	Wait and retry — see Rate Limiting

Server errors (5xx)

Code	HTTP Status	Description	What to do
`internal_error`	500	Unexpected server error	Retry after a short delay. If persistent, contact support.
`not_implemented`	501	Feature not available yet	This endpoint is planned but not yet released
`bad_gateway`	502	External service error	Retry after a short delay
`service_unavailable`	503	Temporarily unavailable	Retry with exponential backoff

Handling errors in code

Node.js

const response = await fetch('https://api.vantagekit.com/v1/deal-rooms/invalid-id', {
  headers: { 'Authorization': `Bearer ${apiKey}` },
})

if (!response.ok) {
  const { error, code, details } = await response.json()

  switch (code) {
    case 'unauthorized':
      // Re-authenticate or check API key
      break
    case 'rate_limit':
      // Wait for Retry-After header and retry
      const retryAfter = response.headers.get('Retry-After')
      await new Promise(r => setTimeout(r, Number(retryAfter) * 1000))
      break
    case 'not_found':
      // Resource doesn't exist
      break
    default:
      console.error(`API error: ${code} — ${error}`)
  }
}

Python

response = requests.get(
    f'https://api.vantagekit.com/v1/deal-rooms/{deal_room_id}',
    headers={'Authorization': f'Bearer {api_key}'},
)

if response.status_code == 429:
    retry_after = int(response.headers.get('Retry-After', 60))
    time.sleep(retry_after)
elif response.status_code >= 400:
    body = response.json()
    raise Exception(f"API error {body['code']}: {body['error']}")

Error response format

Error codes

Client errors (4xx)

Server errors (5xx)

Handling errors in code

On this page