Handling Error in the API

Overview

Our API follows a consistent error-handling format based on the JSON:API error specification. When an error occurs, the response body will include an errors array containing detailed information about each issue.

Error Response Format

An error response is always returned with an appropriate HTTP status code. The structure of the response is as follows:

{
  "errors": [
    {
      "status": "<HTTP Status Code>",
      "title": "<Error Type>",
      "detail": "<Error Message>",
      "source": {
        "pointer": "<JSON Pointer to the Error Location>"
      }
    }
  ]
}

Example Response

{
  "errors": [
    {
      "status": 422,
      "title": "Verse::Error::ValidationFailed",
      "detail": "must be a string",
      "source": {
        "pointer": "/data/attributes/category"
      }
    },
    {
      "status": 422,
      "title": "Verse::Error::ValidationFailed",
      "detail": "must be a string",
      "source": {
        "pointer": "/data/relationships/project/data/id"
      }
    }
  ]
}

Error Response Fields

Each error object includes the following fields:

status (string or integer): The HTTP status code associated with the error.
title (string): A short error type identifier, typically namespaced to indicate the module generating the error.
detail (string): A human-readable explanation of the error.
source.pointer (string): A JSON Pointer indicating the location of the error in the request payload.

Common Error Codes

Status Code	Meaning
`400`	Bad Request - The request is malformed or invalid.
`401`	Unauthorized - Authentication is required.
`403`	Forbidden - The request is understood but not allowed.
`404`	Not Found - The requested resource does not exist.
`422`	Unprocessable Entity - The request data contains validation errors.
`500`	Internal Server Error - An unexpected error occurred on the server.

Common Error Titles

Code	Title	Meaning
`400`	`Verse::Error::BadRequest`	The request is malformed or invalid.
`401`	`Verse::Error::Authorization`	The request requires authentication.
`403`	`Verse::Error::Unauthorized`	The request is understood but not allowed.
`404`	`Verse::Error::NotFound`	The requested resource or path does not exist.
`404`	`Verse::Error::RecordNotFound`	The requested path exist, but the resource itself does not exist.
`422`	`Verse::Error::ValidationFailed`	The request data failed validation.
`422`	`Verse::Error::CannotCreateRecord`	The server was unable to create the requested record.

Handling Validation Errors

When a validation error occurs (HTTP 422 Unprocessable Entity), the API returns details on which fields failed validation. The source.pointer field helps pinpoint the exact attribute that needs correction.

Example Request That Triggers a Validation Error

{
  "data": {
    "attributes": {
      "category": 123
    },
    "relationships": {
      "project": {
        "data": {
          "id": 456
        }
      }
    }
  }
}

Example Validation Error Response

{
  "errors": [
    {
      "status": 422,
      "title": "Verse::Error::ValidationFailed",
      "detail": "must be a string",
      "source": {
        "pointer": "/data/attributes/category"
      }
    },
    {
      "status": 422,
      "title": "Verse::Error::ValidationFailed",
      "detail": "must be a string",
      "source": {
        "pointer": "/data/relationships/project/data/id"
      }
    }
  ]
}

How to Fix Validation Errors

Ensure that all required fields are included in the request.
Check that the values match the expected data types (e.g., a string instead of a number).
Follow the correct request structure as defined in the API documentation.

Debugging Other Errors

For errors with 500 Internal Server Error, check the details of the error, or contact support. These errors indicate an unhandled issue on the server that may require further investigation.