Errors

In this guide, we'll explore the different types of errors you might encounter while working with the IMMUNE API. Understanding these errors will help you build more robust integrations and handle edge cases gracefully.

Status codes

Here are the HTTP status codes you might receive from the IMMUNE API:

Name
2xx
Description
Success responses indicating your request was processed correctly.
Name
4xx
Description
Client errors indicating issues with your request (authentication, validation, etc.).
Name
5xx
Description
Server errors indicating issues on our end. These are rare and automatically reported to our team.

Error types

{
  "error": {
    "type": "validation_error",
    "message": "Invalid sensor reading value",
    "code": "INVALID_READING",
    "details": {
      "field": "value",
      "constraint": "must be between -100 and 100"
    }
  }
}

Common error codes

Name
AUTHENTICATION_ERROR
Description
Your API key or token is invalid or expired.
Name
RATE_LIMIT_EXCEEDED
Description
You've exceeded your rate limit. Check the X-RateLimit-* headers.
Name
INVALID_READING
Description
The sensor reading data failed validation.
Name
SENSOR_NOT_FOUND
Description
The specified sensor ID doesn't exist.
Name
INVALID_TIMESTAMP
Description
The reading timestamp is in the future or too old.

Rate limits

The IMMUNE API implements rate limiting to ensure stable service for all users. Rate limits are applied per API key and are included in response headers:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9995
X-RateLimit-Reset: 1640995200

If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Our SDKs handle rate limiting automatically with exponential backoff.

Handling errors

Here's how to properly handle errors in your integration:

import { ImmuneClient, ImmuneError } from '@immune/api'

try {
  const client = new ImmuneClient('your-api-key')
  await client.sensors.readings.create({
    sensor_id: 'pump_001',
    value: 23.4,
    timestamp: new Date()
  })
} catch (error) {
  if (error instanceof ImmuneError) {
    switch (error.code) {
      case 'RATE_LIMIT_EXCEEDED':
        // Wait and retry
        await sleep(error.retryAfter)
        break
      case 'INVALID_READING':
        // Log validation error
        console.error('Invalid reading:', error.details)
        break
      case 'SENSOR_NOT_FOUND':
        // Handle missing sensor
        await provisionSensor('pump_001')
        break
      default:
        // Handle other errors
        console.error('API Error:', error.message)
    }
  }
}

Best practices

Always implement error handling in your integration
Use exponential backoff for rate limits
Monitor error rates in your dashboard
Set up alerts for unusual error patterns
Keep your API credentials up to date