Error handling

Bearer routes share one envelope. Session-only key routes do not. Quote request_id when you write in.

01Envelope

400Envelope

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description"
  },
  "meta": {
    "request_id": "req_abc123def456",
    "timestamp": "2026-02-01T12:00:00Z"
  }
}

02Codes

Status	Code	When
400	VALIDATION_ERROR	Missing project_id, short topic, unknown platform
400	NO_PROJECT	No project on the account, or none passed
401	UNAUTHORIZED	No Bearer, bad key, expired key
402	INSUFFICIENT_CREDITS	Wallet cannot cover the job
403	FORBIDDEN	Missing write, wrong scope, or consent required
404	NOT_FOUND	Wrong id, or not yours
409	CONFLICT	Already published
412	PRECONDITION_FAILED	Still generating, or no connected channel
429	RATE_LIMIT_EXCEEDED	Sleep Retry-After
500	INTERNAL_ERROR	Retry with backoff. Quote the id.

03Examples

400 Validation

400VALIDATION_ERROR

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "topic: String must contain at least 3 character(s), project_id: Required"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-01T12:00:00Z"
  }
}

402 Credits

402INSUFFICIENT_CREDITS

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "This operation requires 2.4 credits but your balance is 1.2"
  },
  "meta": {
    "request_id": "req_ghi789",
    "timestamp": "2026-02-01T12:00:00Z"
  }
}

412 Not ready

412PRECONDITION_FAILED

{
  "success": false,
  "error": {
    "code": "PRECONDITION_FAILED",
    "message": "Content is still generating. Poll /api/v1/social/content/{id} until status is ready."
  },
  "meta": {
    "request_id": "req_pqr678",
    "timestamp": "2026-02-01T12:00:00Z"
  }
}

Session key routes return { "error": "…" } with no envelope. See /docs/api-reference/api-keys.