Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests. All error responses include a structured error object with details about what went wrong.

Error Response Format

json

{
  "error": {
    "code": "invalid_image_format",
    "message": "Image must be in JPEG, PNG, or WebP format",
    "details": {
      "received_format": "GIF"
    }
  },
  "request_id": "req_abc123"
}

Status Codes

400

Bad Request

Invalid parameters or malformed request body

401

Unauthorized

Missing or invalid API key

403

Forbidden

API key lacks required permissions

404

Not Found

Requested endpoint does not exist

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Server encountered an error

503

Service Unavailable

Server temporarily unavailable

Best Practices

1.Always include error handling for 4xx and 5xx responses in your integration
2.Log the request_id for debugging purposes when contacting support
3.Implement retry logic with exponential backoff for 5xx errors
4.Validate input before sending requests to avoid 400 errors

Example Error Handling

javascript

async function detectObjects(imageUrl) {
  try {
    const response = await fetch('/api/detect', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ image: imageUrl })
    });

    if (!response.ok) {
      const error = await response.json();
      console.error('API Error:', error.error.code, error.error.message);
      throw new Error(error.error.message);
    }

    return await response.json();
  } catch (error) {
    console.error('Request failed:', error.message);
    throw error;
  }
}