Errors

How the gitvetrix.com REST API reports failures: the JSON error envelope, the HTTP status code conventions, and a catalog of representative messages. For authentication, pagination, and host conventions see reference/conventions.md.

The error envelope

Every error response is application/json with a top-level error string. There are three shapes, in increasing detail:

{ "error": "repository not found" }

Some handlers add an optional detail string with a secondary, operator-readable explanation (for example, the offending field and parse reason on a malformed request body):

{
  "error": "invalid request body",
  "detail": "field \"per_page\": expected integer"
}

Validation failures may add a stable, machine-readable error_code alongside the human-readable message:

{
  "error": "organization policy exceeds the application cap",
  "error_code": "org_policy_exceeds_app_cap"
}

Branching on errors

Branch on the HTTP status code first.
When you need to distinguish specific failures within one status, branch on error_code where it is present.
Treat the error string as human-readable copy — it can change wording without notice. Do not pattern-match application logic on it.

Status code conventions

Status	Meaning
`400 Bad Request`	Malformed request: invalid JSON, a missing required field, or an unknown field.
`401 Unauthorized`	Missing or invalid credentials — no token, an expired JWT, or an unknown token.
`403 Forbidden`	Authenticated, but the caller lacks the required permission or scope for a resource it is allowed to see.
`404 Not Found`	The resource does not exist — or it exists but is private and the caller may not read it (see below).
`409 Conflict`	The request conflicts with current state (for example, a duplicate or a concurrent modification).
`422 Unprocessable Entity`	The request is well-formed but fails validation (for example, invalid pipeline YAML or a value out of bounds). May carry an `error_code`.
`429 Too Many Requests`	A rate-limit scope was exceeded. See rate-limits.md.
`500 Internal Server Error`	An unexpected server-side failure. The body keeps the `error` field and may add `detail`.
`502 Bad Gateway`	An upstream dependency failed (for example, minting a presigned storage URL).
`503 Service Unavailable`	A feature is staged but its backing dependency is not wired on this deployment. The message names the missing component.

404, not 403, for private resources

When a caller cannot read a private repository, issue, or merge request, the API returns 404 Not Found with the same body it would return if the resource did not exist — for example repository not found or issue not found. It does not return 403. This is deliberate: returning 403 would confirm that the resource exists, letting an unauthorized caller enumerate private names. A 403 is reserved for a capability denial on a resource the caller is allowed to see (for example, a read-only collaborator attempting a write, or a non-admin calling an admin-only route).

Repository visibility has three tiers — public, internal, and private. Only private resources are hidden behind the enumeration-resistant 404; public and internal repositories are visible to the audiences their tier defines.

401 vs 403

401 Unauthorized means the request was not authenticated: no bearer token, an expired or malformed JWT, or an unrecognized token.
403 Forbidden means the request was authenticated but the identity is not permitted to perform this action.

Representative messages

These are common error strings grouped by status. The list is illustrative, not exhaustive, and the exact wording may change.

400 Bad Request

invalid request body
invalid JSON
name is required, title is required, body is required
invalid user id, invalid group id, invalid pipeline id, invalid MR number
issue_type is read-only; use issue_type_id (see reference/issues-type-write-read-asymmetry.md)

401 Unauthorized

authentication required
invalid credentials
unauthorized

403 Forbidden

forbidden
admin required
account is disabled

404 Not Found

repository not found, owner not found, user not found
issue not found, merge request not found, pipeline not found
artifact not found, version not found, label not found

503 Service Unavailable

rate-limit store not configured
registry not configured
user store not configured, user groups store not configured

A 503 of this kind means the endpoint exists but the feature it serves is not enabled on this particular deployment, not that the request was wrong.