Error Codes

Error Codes

The API returns standard HTTP status codes with JSON error bodies.

Status Codes

Code	Meaning	Cause
200	OK	Successful read
201	Created	Successful create/update
400	Bad Request	Invalid input or missing required fields
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient scope or paused account
404	Not Found	Resource doesn’t exist or you don’t own it
409	Conflict	Duplicate detected (handled via ON CONFLICT)
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side failure

Error Response Format

{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

Common Errors

401 — Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

Causes:

• Missing Authorization header
• Invalid API key format
• Expired or deleted key

Fix: Verify your key starts with ak_live_ and is passed as Bearer ak_live_...

---

403 — Forbidden

{
  "error": "forbidden",
  "message": "Insufficient scope: artworks:write required"
}

Causes:

• Your key tier doesn’t include the required scope
• Your account is paused

Fix: Check your scopes with GET /v1/me. Upgrade to subscriber for write access.

---

400 — Bad Request

{
  "error": "bad_request",
  "message": "Missing required field: title"
}

Causes:

• Missing required fields
• Invalid field types
• Invalid URLs

Fix: Check the endpoint documentation for required fields and valid values.

---

404 — Not Found

{
  "error": "not_found",
  "message": "Artwork not found"
}

Causes:

• Resource doesn’t exist
• You don’t own the resource (entity binding mismatch)

Fix: Verify the ID and that the resource belongs to your entity.

---

429 — Rate Limited

{
  "error": "rate_limited",
  "message": "Rate limit exceeded. Try again after the reset time.",
  "retry_after": 45
}

Fix: Wait for retry_after seconds, or check X-RateLimit-Reset header.

---

500 — Internal Server Error

{
  "error": "internal_error",
  "message": "An unexpected error occurred"
}

Fix: Retry with an idempotency key. If persistent, contact support.

Troubleshooting

Symptom	Likely Cause	Solution
All requests return 401	Key not passed correctly	Check Authorization: Bearer ak_live_... format
Write requests return 403	Read-only key	Upgrade to subscriber account
Artwork not appearing	Sync in progress	Wait a few seconds, check /v1/sync/status
Duplicate artworks	Fingerprint mismatch	Ensure consistent artist_name, title, and year
Rate limited frequently	Hitting 30/min limit	Upgrade tier or batch requests