Error Reference

All Picora API errors return a consistent JSON structure with a machine-readable error code.

Error Response Format

{
  "success": false,
  "error": "Human-readable error description"
}

The HTTP status code indicates the error category, and the error field provides details.

HTTP Status Codes

Status	Meaning
400	Bad Request — Malformed request syntax
401	Unauthorized — Missing or invalid authentication
403	Forbidden — Authenticated but not permitted
404	Not Found — Resource does not exist
422	Unprocessable Entity — Validation failed
429	Too Many Requests — Rate limit exceeded
500	Internal Server Error — Something went wrong on our side

Error Code Reference

Authentication Errors

Code	Status	Description	How to Fix
UNAUTHORIZED	401	Missing Authorization header, invalid API key format, or expired JWT token.	Include a valid Authorization: Bearer sk_live_YOUR_KEY header.
API_KEY_REVOKED	401	The API key has been manually revoked.	Create a new API key in the dashboard.
TOKEN_EXPIRED	401	JWT access token has expired (15-minute lifetime).	Refresh the token via POST /v1/auth/refresh.

Permission Errors

Code	Status	Description	How to Fix
FORBIDDEN	403	You do not have permission to access this resource (e.g., trying to delete another user’s image).	Only access resources that belong to your account.
QUOTA_EXCEEDED	403	You have reached your plan’s storage or bandwidth limit.	Delete unused images or upgrade your plan.
PLAN_REQUIRED	403	This feature requires a paid plan (e.g., video hosting requires Pro).	Upgrade your plan to access this feature.

Resource Errors

Code	Status	Description	How to Fix
NOT_FOUND	404	The requested image, video, or resource does not exist.	Verify the ID is correct. The resource may have been deleted.
CONFLICT	409	Conflicting state (e.g., email already registered, custom domain already taken).	Use a different value or resolve the conflict.

Validation Errors

Code	Status	Description	How to Fix
VALIDATION_ERROR	422	Request body or parameters failed validation. The error field describes which field failed.	Fix the indicated field and retry.
INVALID_FILE_TYPE	422	Uploaded file is not a supported image format.	Use JPEG, PNG, GIF, WebP, AVIF, or SVG.
FILE_TOO_LARGE	422	File exceeds the maximum allowed size for your plan.	Compress the image or upgrade your plan.

Rate Limit Errors

Code	Status	Description	How to Fix
RATE_LIMITED	429	Too many requests in a short period.	Wait and retry. The Retry-After response header indicates when to retry (in seconds).

Server Errors

Code	Status	Description	How to Fix
INTERNAL	500	An unexpected server error occurred.	Retry after a short delay. If the problem persists, contact support@picora.com with the request details.
STORAGE_ERROR	500	Failed to write to object storage.	Retry the request. If persistent, contact support.

Handling Errors in Code

const response = await fetch('https://api.picora.com/v1/images', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer sk_live_YOUR_KEY' },
  body: formData,
});

if (!response.ok) {
  const error = await response.json();
  console.error(`Upload failed: ${error.error}`);
  // error.error contains the human-readable description
}

const { data } = await response.json();
console.log('Uploaded:', data.url);