Errors - Folkyn API

All error bodies are JSON (messages in English). error.code is an integer and always matches the HTTP status of the response.

Shape

{
  "error": {
    "code": 400,
    "message": "Field \"name\" is required",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "details": {
      "field": "name",
      "reason": "required_field"
    }
  }
}

request_id — correlate with the X-Request-Id response header.
details — optional object; extra keys allowed for forward compatibility.

HTTP status reference

HTTP	Typical case
400	Validation (bad JSON, missing field, duplicate name on create tag / project code, …)
401	Missing API key, invalid key, or revoked key
403	Forbidden (action or resource not allowed for this key / team)
404	Resource not found (e.g. activity report not visible for this team)
429	Rate limited (`details.retryAfterSeconds`; see Rate limits)
500	Unexpected server error

Distinguish multiple 401 or 400 cases using message and details.

Validation `details.reason` (create tag / project code)

When code is 400 from those endpoints, details.reason may be:

invalid_json — body is not valid JSON
required_field — e.g. missing name (details.field may be name)
duplicate_name — name already exists for the team (details.field may be name)

Full JSON schemas: OpenAPI components PublicError, PublicErrorDetails, PartnerValidationErrorReason (see API Reference in this site, sourced from openapi.yaml).