Error Handling

When an API request fails, the response body contains an error object with a machine-readable code and a human-readable message.

Error Response Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable description of the error"
  }
}

Error Codes

Error Code	HTTP Status	Description
UNAUTHORIZED	401	The API key is missing, invalid, or has been revoked.
INVALID_REQUEST	400	The request is malformed or contains invalid parameters. Check the message field for details.
NOT_FOUND	404	The requested resource does not exist.
RATE_LIMITED	429	You have exceeded the rate limit. Wait and retry after the period indicated in the response headers.
INTERNAL_ERROR	500	An unexpected error occurred on the server. If this persists, contact support.

HTTP Status Codes

The API uses standard HTTP status codes:

Status Code	Meaning
200	Success. The request completed successfully.
400	Bad Request. The request was invalid.
401	Unauthorized. Authentication failed.
404	Not Found. The resource does not exist.
429	Too Many Requests. Rate limit exceeded.
500	Internal Server Error. Something went wrong on our end.

Error Response Examples

Missing API Key

curl -X GET "https://api.convotic.com/v1/info"

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing X-API-Key header"
  }
}

Invalid Parameter

curl -X GET "https://api.convotic.com/v1/contacts?limit=500" \
  -H "X-API-Key: your-api-key-here"

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Parameter 'limit' must be between 1 and 100"
  }
}

Resource Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Conversation 'conv_invalid' not found"
  }
}

Rate Limited

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 12 seconds."
  }
}

Handling Errors in TypeScript

interface ApiError {
  error: {
    code: string;
    message: string;
  };
}

async function apiRequest(path: string): Promise<any> {
  const response = await fetch(`https://api.convotic.com/v1${path}`, {
    headers: {
      "X-API-Key": "your-api-key-here",
    },
  });

  if (!response.ok) {
    const body: ApiError = await response.json();
    switch (body.error.code) {
      case "RATE_LIMITED":
        // Wait and retry
        console.warn("Rate limited, retrying...");
        break;
      case "UNAUTHORIZED":
        // Check API key
        throw new Error("Invalid API key");
      default:
        throw new Error(`API error: ${body.error.message}`);
    }
  }

  return response.json();
}