Error Handling

Understand how SEO Boost Hub returns API errors so your integration can recover gracefully.

Error Response Format

All error responses follow a consistent JSON structure:

{
  "error": {
    "code": "resource_not_found",
    "message": "The requested location could not be found.",
    "details": {
      "resource": "location",
      "id": "loc_invalid123"
    }
  }
}

HTTP Status Codes

Status Code	Meaning	Description
`400`	Bad Request	The request was malformed or missing required fields.
`401`	Unauthorized	Authentication failed. Check your API key.
`403`	Forbidden	Your API key lacks the required scope for this action.
`404`	Not Found	The requested resource does not exist.
`409`	Conflict	A resource conflict occurred (e.g., duplicate entry).
`422`	Unprocessable Entity	Validation failed. Check the errors array for details.
`429`	Too Many Requests	Too many requests. Slow down and retry after the reset window.
`500`	Internal Server Error	An unexpected server error occurred. Contact support if it persists.

Validation Errors

When a 422 response is returned, the error object includes a details array with field-level validation messages:

{
  "error": {
    "code": "validation_error",
    "message": "The given data was invalid.",
    "details": {
      "name": [
        "The name field is required."
      ],
      "city": [
        "The city field is required.",
        "The city must be a string."
      ],
      "country": [
        "The country must be a valid ISO 3166-1 alpha-2 code."
      ]
    }
  }
}

Error Codes

The following application-level error codes may appear in the code field:

Code	Description
`authentication_failed`	Authentication credentials are missing or invalid
`insufficient_permissions`	Insufficient permissions for the requested action
`resource_not_found`	The requested resource was not found
`resource_conflict`	Resource already exists or conflicts with current state
`validation_error`	Request body failed validation rules
`rate_limit_exceeded`	Rate limit exceeded for your current plan
`internal_error`	An unexpected server-side error occurred