Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.knouds.ai/llms.txt

Use this file to discover all available pages before exploring further.

All non-2xx responses from the Knouds API return a JSON body. At minimum it contains error (a human-readable message) and code (a machine-readable constant). Some errors include additional context fields to help you diagnose the problem without guessing. 
{ "error": "<message>", "code": "<CODE>", ...context }

​
Error reference

HTTP statusCodeMeaning
400INVALID_INPUTSThe request body is malformed or missing required fields. Check that inputs is a non-array object.
400INVALID_SLUGThe workflow slug or model internalName in the URL contains invalid characters. Slugs must be lowercase letters, digits, and hyphens only.
400INVALID_SCOPEThe scope value supplied when assigning a key scope is not recognized.
401(no code)The x-api-key header is missing, the key has been revoked, or the key is invalid.
402INSUFFICIENT_CREDITSYour account does not have enough credits to complete the request. Top up your credit balance to continue.
402grant_exhaustedYour trial grant for this model has been fully used. Topping up credits will not unlock further access — you must upgrade your plan tier.
403SCOPE_DENIEDYour key’s scope is below the minimum required by this endpoint. The response includes required and actual scope fields.
403MODEL_TIER_REQUIREDThe model you are trying to run requires a higher plan tier than your account currently holds.
404MODEL_NOT_FOUNDThe internalName in the URL does not match any enabled registry model. Only non-native registry models are reachable via the models endpoint.
404(message)The workflow slug in the URL does not match any workflow you own.
429RATE_LIMIT_EXCEEDEDYou have exceeded the per-minute request limit for your scope. Check the Retry-After header and wait before retrying.
500EXECUTION_FAILEDThe upstream provider call failed. This is not a client error — retry with exponential back-off.

​
Distinguishing the two 402 codes

Two different situations both return 402, but they require different responses from you:
  • INSUFFICIENT_CREDITS — you have a valid plan and the model is accessible, but your credit balance is too low. Go to Settings → Billing and top up your credits.
  • grant_exhausted — your plan includes a limited trial grant for this model (for example, 3 free lifetime generations on a Free plan) and you have used them all. Topping up credits will not help here. You need to upgrade to a higher plan tier that provides either continued trial access or unrestricted billing access to the model.
If you receive grant_exhausted, adding credits to your account will not resolve the error. The grant is a tier-level feature, not a credit-level one. Upgrade your plan to regain access.

​
SCOPE_DENIED response shape

When your key’s scope is below what an endpoint requires, the response includes the two scope values so you can act without guessing: 
{
  "error": "Insufficient scope",
  "code": "SCOPE_DENIED",
  "required": "admin",
  "actual": "deployment"
}
Use required to determine which plan tier provides the access you need. See Authentication for the scope-to-tier mapping.

​
Handling errors in code

const response = await fetch(url, options);

if (!response.ok) {
  const err = await response.json();

  if (response.status === 429) {
    const retryAfter = parseInt(response.headers.get('Retry-After') || '10', 10);
    // Wait and retry
  } else if (err.code === 'INSUFFICIENT_CREDITS') {
    // Prompt user to top up credits
  } else if (err.code === 'grant_exhausted') {
    // Prompt user to upgrade plan — credits won't help
  } else if (err.code === 'SCOPE_DENIED') {
    console.error(`Need ${err.required} scope, have ${err.actual}`);
  }
}