10 min read

Error Handling

Handle API errors gracefully with proper error codes and messages.

Error Response Format

All API errors return a consistent JSON structure:

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_required_field",
    "message": "The 'itemValue' field is required for shipping_protection quotes",
    "param": "coverage.itemValue",
    "requestId": "req_abc123"
  }
}

HTTP Status Codes

2xx

Success

200 - Request succeeded

201 - Resource created

204 - No content (successful delete)

4xx

Client Errors

400 - Bad request (invalid parameters)

401 - Unauthorized (invalid API key)

403 - Forbidden (insufficient permissions)

404 - Resource not found

409 - Conflict (e.g., duplicate request)

422 - Unprocessable entity (validation failed)

429 - Too many requests (rate limited)

5xx

Server Errors

500 - Internal server error

502 - Bad gateway

503 - Service unavailable

504 - Gateway timeout

Error Types

invalid_request_error

The request was malformed or missing required parameters

authentication_error

Invalid or missing API key

rate_limit_error

Too many requests in a short period

api_error

Internal server error (retry with backoff)

Handling Errors in Code

import { CoverKit, CoverKitError } from '@coverkit/sdk';

const coverkit = new CoverKit({ apiKey: process.env.COVERKIT_API_KEY });

try {
  const quote = await coverkit.quotes.create({
    product: 'shipping_protection',
    coverage: { itemValue: 15000 },
  });
} catch (error) {
  if (error instanceof CoverKitError) {
    switch (error.type) {
      case 'invalid_request_error':
        console.error('Invalid request:', error.message);
        console.error('Problem field:', error.param);
        break;
      case 'authentication_error':
        console.error('Check your API key');
        break;
      case 'rate_limit_error':
        // Wait and retry
        const retryAfter = error.headers?.['retry-after'] || 60;
        await sleep(retryAfter * 1000);
        break;
      case 'api_error':
        // Retry with exponential backoff
        break;
      default:
        console.error('Unexpected error:', error.message);
    }
  }
}

Common Error Codes

Code	Description
`missing_required_field`	A required field is missing
`invalid_field_value`	Field value is invalid or out of range
`quote_expired`	Quote has expired and cannot be bound
`policy_not_active`	Policy is not in active status
`payment_failed`	Payment processing failed
`duplicate_request`	Idempotency key already used
`resource_not_found`	Requested resource does not exist

Retry Strategy

For 5xx errors and rate limits, implement exponential backoff: wait 1s, 2s, 4s, 8s between retries. Our SDKs handle this automatically.