Error Handling

The Seelab API provides standardized error responses to help you understand what went wrong and how to address the issue. All error responses include an HTTP status code, an internal error code, a message, and additional details if necessary.

Error messages may vary over time or between different API endpoints. Therefore, you should not rely on the error message itself for client-side processing but instead use the provided error codes.

Common Error Responses

400 Bad Request

The request was invalid or cannot be otherwise served, often due to input validation errors.

• Error Code: 1001 (Input validation error on one or more fields)
• Example Response:
  JSON

  {
    "error": 1001,
    "message": "Invalid request parameters",
    "data": {
      "missing": ["type"]
    }
  }
  

401 Unauthorized

The request lacks valid authentication credentials. This occurs when the API key is missing, invalid, or has been revoked.

• Error Code: 1008 (Authentication failed)
• Example Response:
  JSON

  {
    "error": 1008,
    "message": "Authentication failed",
    "data": []
  }
  

403 Forbidden

The authenticated user does not have permission to perform the requested action. This might be due to insufficient privileges or restricted API keys.

• Error Code: 1005 (Resource is read-only)
• Example Response:
  JSON

  {
    "error": 1005,
    "message": "Access denied",
    "data": []
  }
  

404 Not Found

The requested resource could not be found. This might occur if the provided id does not match any existing records.

• Error Code: 1002 (Resource not found for the client identity)
• Example Response:
  JSON

  {
    "error": 1002,
    "message": "Resource not found",
    "data": []
  }
  

429 Too Many Requests

The request rate limit has been exceeded. The client should wait before retrying.

• Error Code: 1000 (Reached limits associated with the resource)
• Example Response:
  JSON

  {
    "error": 1000,
    "message": "Rate limit exceeded",
    "data": {
      "type": "rateLimit",
      "limit": 3,
      "retryAfter": 10
    }
  }
  

500 Internal Server Error

An error occurred on Seelab's servers. Please try again later or contact support if the issue persists.

• Error Code: 1004 (Internal server error)
• Example Response:
  JSON

  {
    "error": 1004,
    "message": "Internal server error",
    "data": []
  }
  

Handling Errors Gracefully

To handle errors effectively, it is recommended to:

• Check Status Codes: Always check the HTTP status code of the response to determine if the request was successful.
• Use Error Codes: Use the provided error codes to identify and handle specific errors in your client.
• Implement Retry Logic: For rate limits (429), implement retry logic with exponential backoff to avoid overwhelming the server.
• Log Errors: Log errors with sufficient detail to help diagnose issues later.
• Contact Support: For persistent issues or unclear errors, contact [email protected].