Error Codes

API error responses include a JSON body with error (message) and optionally code (machine-readable). Use code for programmatic handling.

Error codes table

Code	HTTP Status	Description
MISSING_AUTH	401	Missing or invalid Authorization header
INVALID_OR_EXPIRED_TOKEN	401	Invalid or expired token
EMAIL_NOT_VERIFIED	403	Email not verified; check your inbox for the confirmation link
RATE_LIMITED	429	Too many requests
FILE_TOO_LARGE	413	File too large
FILE_NOT_FOUND	404	File not found
NOT_FOUND	404	Resource not found
STORAGE_LIMIT_REACHED	403	Storage limit reached
FILE_COUNT_LIMIT_REACHED	403	File count limit reached
TRIAL_ENDED	403	Trial ended; upgrade or your files will be removed in 15 days
IMAGE_OPS_LIMIT_REACHED	429	Image operations limit reached for this period
ORIGIN_READS_LIMIT_REACHED	429	Origin reads limit reached for this period
SERVER_BUSY	503	Server busy; try again shortly
CONTENT_TYPE_NOT_ALLOWED	400	Content-Type not allowed for upload
CONTENT_VERIFICATION_FAILED	400	File content does not match declared type
INVALID_REQUEST	400	Invalid request

Response format

{
  "error": "Human-readable message",
  "statusCode": 400,
  "code": "MACHINE_READABLE_CODE"
}

Handling errors

JavaScript

const res = await fetch('https://api.atiru.io/files', { ... })
const data = await res.json()
if (!res.ok) {
  switch (data.code) {
    case 'MISSING_AUTH':
    case 'INVALID_OR_EXPIRED_TOKEN':
      // Re-authenticate
      break
    case 'RATE_LIMITED':
      const retryAfter = res.headers.get('Retry-After')
      await sleep(parseInt(retryAfter || '60') * 1000)
      // Retry
      break
    case 'FILE_TOO_LARGE':
      // Show size limit to user
      break
    default:
      console.error(data.error)
  }
}

Python

res = requests.post(...)
if not res.ok:
    data = res.json()
    if data.get('code') == 'RATE_LIMITED':
        retry_after = int(res.headers.get('Retry-After', 60))
        time.sleep(retry_after)
        # Retry
    elif data.get('code') == 'FILE_TOO_LARGE':
        # Show size limit to user
        pass
    else:
        print(data.get('error'))