Error Codes

Complete reference of UploadKit error codes, HTTP status codes, and troubleshooting suggestions.

Every error response from the UploadKit API has the same shape:

{
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File size 6291456 bytes exceeds the 4194304 byte limit",
    "suggestion": "Upgrade your plan at app.uploadkit.dev/billing"
  }
}

Field	Description
`code`	Machine-readable error code — use this in your error handling logic
`message`	Human-readable description of what went wrong
`suggestion`	Optional — actionable fix (shown to developers, not end users)

Error Codes

Authentication Errors

Code	HTTP Status	Description	Fix
`UNAUTHORIZED`	401	API key is missing, malformed, or has been revoked	Check your `x-api-key` header; create a new key if revoked

Upload Errors

Code	HTTP Status	Description	Fix
`FILE_TOO_LARGE`	413	File size exceeds the route's `maxFileSize` or your tier's limit	Reduce file size, increase route limit, or upgrade tier
`FILE_TYPE_NOT_ALLOWED`	415	MIME type not in the route's `allowedTypes` list	Check the route config in your dashboard
`UPLOAD_NOT_FOUND`	404	`fileId` does not exist or belongs to another project	Verify the `fileId` came from a `/upload/request` call on the same project
`UPLOAD_NOT_VERIFIED`	422	R2 object not found when confirming — the PUT upload may have failed	Retry the upload from the beginning

Resource Errors

Code	HTTP Status	Description	Fix
`NOT_FOUND`	404	The requested resource (file, project, route) does not exist	Check the ID or key in the request

Quota and Billing Errors

Code	HTTP Status	Description	Fix
`TIER_LIMIT_EXCEEDED`	403	Monthly upload count, storage, or project limit reached	Upgrade your plan at app.uploadkit.dev/billing
`RATE_LIMITED`	429	Too many requests within the sliding window	Wait for the window to reset (see `Retry-After` header)

Server Errors

Code	HTTP Status	Description	Fix
`INTERNAL_SERVER_ERROR`	500	Unexpected server-side error	Retry with exponential backoff; report persistent issues at github.com/uploadkit/uploadkit

Rate Limit Headers

When rate-limited (429), the response includes headers to guide your retry logic:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 23

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

Header	Description
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Requests remaining in the current window (0 when limited)
`Retry-After`	Seconds until the sliding window resets

Handling Errors in Code

const response = await fetch('https://api.uploadkit.dev/api/v1/upload/request', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.UPLOADKIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ fileName, fileSize, contentType, routeSlug }),
});

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

  switch (error.code) {
    case 'FILE_TOO_LARGE':
      throw new Error('Please upload a smaller file.');
    case 'FILE_TYPE_NOT_ALLOWED':
      throw new Error('This file type is not supported.');
    case 'RATE_LIMITED':
      const retryAfter = response.headers.get('Retry-After');
      throw new Error(`Too many requests. Try again in ${retryAfter}s.`);
    case 'TIER_LIMIT_EXCEEDED':
      throw new Error('Upload quota reached. Upgrade your plan.');
    default:
      throw new Error(error.message);
  }
}

When using the @uploadkitdev/core or @uploadkitdev/react SDK, errors are surfaced via the onError callback with the same code values. You do not need to parse the HTTP response manually.

Error Codes

On this page