Errors and pagination

Success envelope

Single resources (GET by id, create, actions) return the entity at the top level:

{ "...": "..." }

Lists:

{
  "data": [ { "...": "..." } ],
  "meta": {
    "limit": 20,
    "offset": 0,
    "count": 42
  }
}

count is the total number of matching rows (not just the current page).

List endpoints accept:

Query	Default	Notes
`limit`	`20`	Clamped to a maximum of `100`
`offset`	`0`	Zero-based

Invalid or missing values fall back to the defaults.

An offset past the last matching row returns 200 with data: [] and the same meta shape.

curl "https://api.skillflare.co/v1/candidates?limit=50&offset=50" \
  -H "x-api-key: sk_skillflare_YOUR_KEY"

{
  "error": "VALIDATION_ERROR",
  "message": "email must be an email address"
}

Code	Typical status	When
`UNAUTHORIZED`	401	Missing/invalid API key
`FORBIDDEN`	403	Authenticated but not allowed
`NOT_FOUND`	404	Unknown route or resource
`VALIDATION_ERROR`	400	Bad UUID, body fields, or business-rule validation
`CONFLICT`	409	Duplicate organization slug (`Slug is already in use`)
`INTERNAL_ERROR`	500	Unexpected server failure

Unknown paths return NOT_FOUND with message Route not found.