Errors

Every non-2xx response from /api/v1 uses the same JSON envelope:

json

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

Treat error.code as the stable machine-readable value. error.message is human-readable context and may contain validation details.

Error reference

Status	Code	Meaning	Retry?
400	`invalid_request`	The body, parameter, cursor, or required header is invalid.	Fix the request.
401	`unauthorized`	The API key is missing, malformed, expired, or revoked.	Use a valid key.
403	`forbidden`	The key lacks a scope, or its owner's role lacks permission.	Change access.
403	`plan_required`	The team does not currently have Public API access.	Activate Pro access.
404	`not_found`	The file does not exist or belongs to another team.	No.
413	`payload_too_large`	The direct upload exceeds 100 MiB.	Upload through the app.
415	`unsupported_media_type`	The normalized content type is not accepted.	Change the file or type.
429	`rate_limited`	The key's request budget is exhausted.	Wait for `Retry-After`.
507	`quota_exceeded`	The team's storage quota is full.	Free storage or increase quota.
500	`internal_error`	An unexpected server error occurred.	Retry with backoff.

JavaScript error helper

async function apiFetch(path, options = {}) {
  const response = await fetch(`${process.env.NEW_ARCHIVE_URL}${path}`, {
    ...options,
    headers: {
      Authorization: `Bearer ${process.env.NEW_ARCHIVE_API_KEY}`,
      ...options.headers,
    },
  })

  const body = await response.json()
  if (!response.ok) {
    const error = new Error(body.error?.message ?? `HTTP ${response.status}`)
    error.code = body.error?.code
    error.status = response.status
    error.retryAfter = Number(response.headers.get("retry-after") ?? 0)
    throw error
  }
  return body
}

Retry rate limits

Respect Retry-After when present. Add a fallback and cap retries so a broken integration cannot loop forever.

Validation errors

Validation failures identify the field in message. They are safe to log, but do not log the request's Authorization header.

json

{
  "error": {
    "code": "invalid_request",
    "message": "limit: Too big: expected number to be <=100"
  }
}

PreviousUpload limits