Skip to main content

​
Error response format

All errors follow a consistent JSON structure: 
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description."
  }
}

​
HTTP status codes

CodeMeaning
200Success
201Created
202Accepted (async job queued)
400Bad Request — invalid parameters
401Unauthorized — missing or invalid API key
402Payment Required — insufficient credits
403Forbidden — valid key but insufficient scope
404Not Found — resource does not exist
409Conflict — duplicate request (idempotency)
422Unprocessable Entity — validation error
429Too Many Requests — rate limited
500Internal Server Error

​
Common error codes

CodeDescription
UNAUTHORIZEDAPI key is missing or invalid
FORBIDDENKey lacks the required scope
INSUFFICIENT_CREDITSWallet balance too low
RATE_LIMITEDToo many requests
VALIDATION_ERRORRequest body failed validation
RESOURCE_NOT_FOUNDThe requested resource does not exist
IDEMPOTENCY_CONFLICTA request with this idempotency key was already processed
MODEL_NOT_AVAILABLEThe requested AI model is not available on your plan
JOB_FAILEDAn async job encountered an error

​
Idempotency

For POST requests, include an Idempotency-Key header to prevent duplicate operations: 
curl -X POST https://api.smartlyq.com/v1/articles/generate \
  -H "Authorization: Bearer sqk_live_xxxxxxxxxxxx" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{ "title": "My Article", "model": "gpt-4.1-nano" }'
Idempotency keys expire after 24 hours.