Error Handling

When an API request fails, Poomi returns a JSON error response with an appropriate HTTP status code.

Error Response Format

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description."
  }
}

Error Codes

Client Errors

HTTP Status	Code	Description
400	`VALIDATION_ERROR`	Request body is malformed or missing required fields
400	`MISSING_IMAGE`	Endpoint requires an image input but none was provided
400	`MISSING_TEXT`	Endpoint requires a text input but none was provided
400	`MISSING_INPUT`	Endpoint requires image and/or text input but none was provided
400	`INVALID_IMAGE`	Image format is unsupported or file size exceeds the limit
401	`UNAUTHORIZED`	Missing or invalid Authorization header
401	`INVALID_KEY`	The API key does not exist
402	`INSUFFICIENT_CREDITS`	Account does not have enough credits for this request
403	`KEY_DISABLED`	The API key has been disabled
403	`KEY_REVOKED`	The API key has been revoked
403	`KEY_EXPIRED`	The API key has expired
404	`NOT_FOUND`	The endpoint slug does not exist or is not published

Server Errors

HTTP Status	Code	Description
502	`AI_CALL_FAILED`	The upstream AI model call failed

Handling Errors

Check the HTTP Status Code

4xx errors are client errors — fix the request before retrying
5xx errors are server errors — safe to retry with exponential backoff

Example: Error Handling in Code

const response = await fetch('https://www.poomi.pet/api/v1/{endpoint-slug}', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer pk_your_api_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ image: base64Data }),
});

if (!response.ok) {
  const { error } = await response.json();

  switch (error.code) {
    case 'INSUFFICIENT_CREDITS':
      // Prompt user to add credits
      break;
    case 'INVALID_KEY':
      // Check API key configuration
      break;
    case 'AI_CALL_FAILED':
      // Retry the request
      break;
    default:
      console.error(`API error: ${error.code} - ${error.message}`);
  }
}

Retry Strategy

For 5xx errors, use exponential backoff:

Wait 1 second, retry
Wait 2 seconds, retry
Wait 4 seconds, retry
Give up after 3 attempts

On this page