Errors

Every non-2xx response from the developer API uses the same envelope:

json

{
  "error": {
    "code": "FILE_NOT_FOUND",
    "message": "The file could not be found.",
    "details": { "issues": { "size": ["Size must be at least 1 byte"] } }
  }
}

code — a stable, machine-readable string (FILE_NOT_FOUND, VALIDATION_ERROR, …). Match on this in error handling, never on message.
message — a human-readable explanation.
details — optional structured context. Validation failures carry a Zod issues map of field → problems.

Infrastructure (storage-provider/database) errors are translated to INTERNAL_ERROR and never leak raw internals or secrets.

Error codes

Status	Code	Meaning
`400`	`VALIDATION_ERROR`	Invalid JSON, body or query parameters
`401`	`UNAUTHORIZED`	Missing, malformed, revoked or expired API key
`404`	`FILE_NOT_FOUND`	File doesn't exist in this project (or is deleted)
`404`	`UPLOAD_NOT_FOUND`	Upload session doesn't exist in this project
`409`	`FILE_NOT_PENDING`	Completing a file that isn't `pending`
`409`	`FILE_NOT_UPLOADED`	Action requires an `uploaded` file
`409`	`FILE_NOT_DELETED`	Restore/delete lifecycle conflict
`409`	`REPLACE_IN_PROGRESS`	A replacement is already pending for this file
`409`	`NO_REPLACE_IN_PROGRESS`	`replace/complete` without a pending replacement
`409`	`UPLOAD_NOT_ACTIVE`	Session has been aborted or completed
`409`	`UPLOAD_EXPIRED`	Session TTL elapsed
`409`	`UPLOAD_PARTS_INCOMPLETE`	Part count/contiguity check failed
`409`	`UPLOAD_SIZE_MISMATCH`	Assembled object size ≠ declared size
`413`	`FILE_TOO_LARGE`	Exceeds the project's maximum file size
`403`	`QUOTA_EXCEEDED`	Project quota exhausted (storage, files, or bandwidth). `details.quota` names which one
`500`	`INTERNAL_ERROR`	Unexpected server error (retry later)

Handling errors in code

import { ApulodiError } from "@apulodi/sdk";

try {
  await apulodi.files.get("file_missing");
} catch (error) {
  if (error instanceof ApulodiError) {
    if (error.code === "FILE_NOT_FOUND") {
      // 404 — the file doesn't exist
    }
    console.log(error.status);    // 404
    console.log(error.details);   // undefined here
  }
}

Network failures and timeouts surface as ApulodiError with status: 0 and code NETWORK_ERROR / TIMEOUT — inspect status before treating it as an HTTP response code.

Next: Pagination — cursor-based paging.

← Usage & Quotas

Pagination →