Errors

Nuelink uses standard HTTP status codes.

All error responses, regardless of status code, share the same envelope:

{
  "status": "error",
  "message": "Human-readable description of what went wrong.",
  "errors": {
    "fieldName": "..."
  }
}

The errors object is always present and always maps field names to messages. Two shapes are possible depending on the error type:

Most errors (401, 403, 404, 429, 500) use a single string per field:

"errors": {
  "authorization": "Token is required"
}

Validation errors (422) follow Laravel’s default and return an array of strings per field, because a single field can fail multiple rules at once:

{
  "errors": {
    "caption": ["The caption field is required when poll is not present."],
    "scheduledAt": [
      "The scheduled at field is required when publish mode is SCHEDULE.",
      "The scheduled at field must be a future date."
    ]
  }
}

On validation failures the key is the request field that failed. On authentication failures the key is authorization. On resource-not-found errors the key identifies the missing resource.

(e.g. brand, collection)

Status code reference

Code	Meaning	Typical cause
200	OK	Successful GET.
201	Created	Successful POST.
401	Unauthorized	Missing, malformed, or revoked API key.
403	Forbidden	Token is valid but doesn’t have access to the requested brand or collection.
404	Not Found	Brand, collection, channel, or media ID doesn’t exist.
422	Unprocessable Entity	Request body failed validation, see errors.
429	Too Many Requests	Rate limit exceeded.
500	Internal Server Error	Something broke on our end. Safe to retry with exponential backoff.

Validation error example

When the caption field is missing and no poll is provided:

Response: 422 Unprocessable Entity:

{
  "status": "error",
  "message": "The given data was invalid.",
  "errors": {
      "caption": [
        "The caption field is required when poll is not present."
      ]
  }
}

Resource-not-found example

When a channel referenced inside a YouTube playlist doesn’t belong to the brand:

Response: 404 Not Found:

{
  "status": "error",
  "message": "Channel not found or does not belong to the brand",
  "errors": {
    "platforms.youtube.playlists.0.channelId": "Channel not found or does not belong to the brand"
  }
}