Error Handling

All errors return a JSON object with an error field. See authentication for API key setup, and CAR import for bulk uploads that can also fail with the codes below.

{
  "error": "storage limit exceeded (9830.0/10240 MB used, 500.0 MB needed). Upgrade to Karma for more storage.",
  "error_code": "PLAN_LIMIT_EXCEEDED",
  "upgrade_url": "https://ipfs.ninja/pricing",
  "plan": "bodhi",
  "nextPlan": "Karma",
  "dimension": "storage",
  "current_mb": 9830,
  "needed_mb": 500,
  "limit_mb": 10240
}

Status codes

Code	Meaning	Common causes
400	Bad Request	Missing or invalid parameters, unsupported content type, invalid JSON body.
403	Forbidden	Missing or invalid API key. Also returned for authenticated requests where the caller isn't allowed to touch the resource (e.g., another user's CID).
402	Payment Required	Storage limit exceeded — upgrade your plan or wait for monthly reset.
404	Not Found	File CID or user not found.
429	Too Many Requests	Gateway bandwidth limit exceeded — wait for monthly reset.
500	Internal Error	Unexpected server error — retry or contact support.

4xx Client errors

4xx codes indicate a problem with the request itself. Check that your API key is valid (401), that your request body is correctly formatted JSON (400), and that your storage quota has not been exceeded (402).

5xx Server errors

A 500 response means an unexpected condition on the server side. Retry the request after a short delay; if the error persists, contact support with the request ID from the response headers.