Errors & Rate Limits

Every common LoreMind API error, what causes it, and how to handle it — plus the rate-limit defaults.

Last verified against LoreMind v1.0.67 (August 2026).

Errors return a JSON body with an error message. Some include extra fields: retryAfter on 429, currentStatus on scanner 409 responses.

Common Errors

Status	Error	Returned by	What to do
400	endpoint-specific validation messages	all endpoints	Fix the request — each endpoint’s error table lists its exact `400` messages (NPC Interaction, Lore Scanner)
401	`Invalid API key`	`POST /npc/interact`	The key is missing, malformed, or revoked — check the full `sk_server_*` key
401	`Invalid authentication`	editor-key endpoints	Missing or invalid Editor Key (`sk_editor_*`)
402	`Insufficient credits`	credit-consuming requests (`/npc/interact`, scanner submit/confirm)	Top up or enable auto-reload — see Insufficient Credits below
403	`Invalid authentication`	`POST /npc/interact`	An Editor Key was used where a Server Key is required
403	`Access denied`	scanner job endpoints	The job belongs to a different project
404	`Project not found`	`POST /npc/interact`	Invalid project or key
404	`Entity Mind not found`	`POST /npc/interact`	Check `entityMindId` against the dashboard
404	`Job not found`	scanner job endpoints	Invalid `jobId`
409	`Job is not awaiting upload`	scanner confirm/cancel	Job already confirmed, expired, or cancelled — the response includes `currentStatus`
429	`Rate limit exceeded`	`POST /npc/interact`	Wait and retry — see Rate Limits below
503	`Generation failed`	`POST /npc/interact`	LLM error — retry

Insufficient Credits (402)

API usage consumes credits from your team balance: your subscription plan’s monthly credit allotment is used first, then top-up credits (which never expire). When the balance runs out, requests fail with 402:


{
  "error": "Insufficient credits"
}

Handle this gracefully in your game and top up (or enable auto-reload) in the dashboard . See Credits & Billing for how costs work.

Rate Limits

NPC interactions (POST /npc/interact) are rate limited per minute, both per player (using playerId) and per project. Defaults are 60 requests/minute per player and 200 requests/minute per project.

Both limits are configurable in Dashboard → Rate Limits.

Response Headers

When rate limited, the API returns 429 with:

Retry-After header — seconds until retry
retryAfter field in the JSON body

SDK Error Codes (Unity)

When you use the Unity SDK, failures surface as codes on NPCResponse.error rather than raw HTTP statuses:

SDK code	HTTP	Meaning
`CONFIG_ERROR`	—	SDK not configured (check Control Panel settings)
`VALIDATION_ERROR`	400	Server rejected the request
`AUTH_FAILED`	401	Invalid API key
`INSUFFICIENT_CREDITS`	402	Out of credits
`RATE_LIMITED`	429	Too many requests (wait `retryAfter` seconds)
`SERVICE_UNAVAILABLE`	503	AI service unavailable (retry)
`REQUEST_FAILED`	other	Other HTTP error (check the `message` field)
`TRANSPORT_ERROR`	—	Request failed to send (check network)

Full details, including custom-backend transport codes, are in the SDK API Reference.

Next Steps

POST /npc/interact - The stable endpoint’s complete error table
Lore Scanner API reference - Per-endpoint scanner errors
Authentication - Key types and how to store them
Credits & Billing - How usage is billed