Error Handling

REST API — All endpoints require authentication via Bearer token. Include Authorization: Bearer {token} in every request. Tokens are managed in GitScrum Settings → API. Base URL: https://services.gitscrum.com — All request paths in this documentation are relative to this base URL.

The GitScrum API uses standard HTTP status codes and returns structured JSON error responses.

HTTP status codes

Error response format

All error responses follow a consistent structure:

{
  "error": "Not Found",
  "message": "The requested resource was not found."
}

Validation errors (422)

Validation errors include field-level details:

{
  "error": "Validation Error",
  "message": "The given data was invalid.",
  "errors": {
    "title": ["The title field is required."],
    "company_slug": ["The selected company slug is invalid."]
  }
}

Each key in the errors object corresponds to a request field, and the value is an array of validation messages.

Authentication errors (401)

{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

Verify your token is valid and included in the Authorization header. See Authentication.

Permission errors (403)

{
  "error": "Forbidden",
  "message": "You do not have permission to perform this action."
}

Check that your account has the required role for the workspace or project.

Best practices

• Check status codes — Always inspect the HTTP status code before parsing the response body.
• Handle retries — Retry 429 and 5xx errors with exponential backoff. Do not retry 4xx client errors.
• Log errors — Capture the full error response (status, message, errors object) for debugging.
• Validate locally — Validate required fields before sending requests to avoid unnecessary 422 responses.
• Display messages — Use the message field to display user-friendly error feedback.