Errors

All API errors follow a consistent format:


{
  "error": {
    "type": "invalid_request",
    "message": "Amount must be greater than 0",
    "param": "amount",
    "code": "amount_invalid"
  }
}

Error types

HTTP Status	Type	Description
`400`	`invalid_request`	Bad or missing parameters
`401`	`authentication_error`	Invalid or missing API key
`404`	`not_found`	Resource not found (or belongs to different merchant)
`429`	`rate_limit`	Too many requests. See Rate Limits.
`500`	`internal_error`	Server-side failure. Contact support if persistent.

Error fields

Field	Type	Description
`type`	string	Error category (always present)
`message`	string	Human-readable description (always present)
`param`	string	The parameter that caused the error (when applicable)
`code`	string	Machine-readable error code (when applicable)

Common errors

Authentication


// Missing or invalid API key
{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key provided"
  }
}

Validation


// Invalid amount
{
  "error": {
    "type": "invalid_request",
    "message": "Amount must be greater than 0",
    "param": "amount",
    "code": "amount_invalid"
  }
}
 
// Metadata too large
{
  "error": {
    "type": "invalid_request",
    "message": "Metadata must be less than 4KB",
    "param": "metadata",
    "code": "metadata_too_large"
  }
}

Rate limiting


{
  "error": {
    "type": "rate_limit",
    "message": "Rate limit exceeded. Retry after 42 seconds."
  }
}

See the X-RateLimit-* response headers for current limits. Details in Rate Limits.

Handling errors


const res = await fetch('https://api.inzilink.com/api/v1/checkouts', { ... })
 
if (!res.ok) {
  const { error } = await res.json()
 
  switch (error.type) {
    case 'authentication_error':
      // Check your API key
      break
    case 'invalid_request':
      // Fix the request parameters
      console.error(`Invalid param: ${error.param} — ${error.message}`)
      break
    case 'rate_limit':
      // Back off and retry
      break
    case 'internal_error':
      // Retry with exponential backoff
      break
  }
}