Error Reference

The API uses conventional HTTP status codes and returns errors in a consistent JSON format. This guide covers all error codes and how to handle them.

Error Response Format

All error responses follow this structure:

400Bad Request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "status": 400,
    "details": {
      "fields": {
        "url": [
          "URL is required",
          "Must be a valid URL"
        ]
      }
    }
  }
}

Field	Type	Description
`error.code`	string	Machine-readable error code (e.g., VALIDATION_ERROR)
`error.message`	string	Human-readable error description
`error.status`	number	HTTP status code (same as response status)
`error.details`	object?	Optional additional context (validation errors, etc.)

HTTP Status Codes

The API uses standard HTTP status codes to indicate success or failure:

Code	Status	Description
200	OK	Request succeeded
201	Created	Resource created successfully
204	No Content	Request succeeded, no body returned (e.g., DELETE)
400	Bad Request	Invalid request body or parameters
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Authenticated but not authorized
404	Not Found	Resource does not exist
409	Conflict	Request conflicts with current state
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error

Error Codes

Complete reference of all error codes, organized by category:

Authentication Errors

UNAUTHORIZED401

Missing or invalid authorization header

The request is missing the Authorization header or uses an invalid format.

Resolution: Include a valid Bearer token: Authorization: Bearer dlr_your_api_key

INVALID_API_KEY401

The provided API key is invalid

The API key does not exist or has never been valid.

Resolution: Verify the API key is correct and was copied in full.

EXPIRED_API_KEY401

The provided API key has expired

The API key had an expiration date that has passed.

Resolution: Create a new API key or update the expiration date.

REVOKED_API_KEY401

The provided API key has been revoked

The API key was manually revoked by the user.

Resolution: Create a new API key from the dashboard.

Permission Errors

FORBIDDEN403

You do not have permission to access this resource

The authenticated user cannot access this resource.

Resolution: Verify you own the resource or have been granted access.

BUSINESS_PLAN_REQUIRED403

API access requires a Business plan subscription

The current subscription does not include API access.

Resolution: Upgrade to the Business plan to enable API access.

INSUFFICIENT_PERMISSIONS403

Your API key does not have permission for this operation

The API key lacks the required read or write permission.

Resolution: Use an API key with appropriate permissions for this operation.

Request Errors

VALIDATION_ERROR400

Request validation failed

The request body or query parameters failed validation.

Resolution: Check the error details for specific field errors and fix them.

NOT_FOUND404

The requested resource was not found

The specified resource ID does not exist or was deleted.

Resolution: Verify the resource ID is correct and the resource exists.

CONFLICT409

The request conflicts with the current state

The operation would create a conflict (e.g., duplicate URL).

Resolution: Check for existing resources with the same unique properties.

Rate Limiting

RATE_LIMITED429

Rate limit exceeded. Please try again later

You have made too many requests in a short period.

Resolution: Wait for the Retry-After period and implement exponential backoff.

Server Errors

INTERNAL_ERROR500

An internal server error occurred

An unexpected error occurred on the server.

Resolution: Retry the request. If the error persists, contact support.

Handling Errors

Best practices for handling API errors in your application:

Error Handling Example

# The API returns errors in a consistent JSON format
curl https://deadlinkradar.com/api/v1/links/invalid-id \
  -H "Authorization: Bearer dlr_your_api_key"

# Returns:
# {
#   "error": {
#     "code": "NOT_FOUND",
#     "message": "The requested resource was not found",
#     "status": 404
#   }
# }

Validation Error Details

Validation errors include detailed field-level error information:

400Bad Request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "status": 400,
    "details": {
      "fields": {
        "url": [
          "URL is required"
        ],
        "check_frequency": [
          "Must be one of: hourly, daily, weekly, monthly"
        ],
        "group_id": [
          "Group not found"
        ]
      }
    }
  }
}

The details.fields object maps field names to arrays of error messages. Use this to display targeted feedback to users.

Rate Limits Endpoints

Back to Rate Limits

Error Reference

The API uses conventional HTTP status codes and returns errors in a consistent JSON format. This guide covers all error codes and how to handle them.

Error Response Format

All error responses follow this structure:

400Bad Request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "status": 400,
    "details": {
      "fields": {
        "url": [
          "URL is required",
          "Must be a valid URL"
        ]
      }
    }
  }
}

Field	Type	Description
`error.code`	string	Machine-readable error code (e.g., VALIDATION_ERROR)
`error.message`	string	Human-readable error description
`error.status`	number	HTTP status code (same as response status)
`error.details`	object?	Optional additional context (validation errors, etc.)

HTTP Status Codes

The API uses standard HTTP status codes to indicate success or failure:

Code	Status	Description
200	OK	Request succeeded
201	Created	Resource created successfully
204	No Content	Request succeeded, no body returned (e.g., DELETE)
400	Bad Request	Invalid request body or parameters
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Authenticated but not authorized
404	Not Found	Resource does not exist
409	Conflict	Request conflicts with current state
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error

Error Codes

Complete reference of all error codes, organized by category:

Authentication Errors

UNAUTHORIZED401

Missing or invalid authorization header

The request is missing the Authorization header or uses an invalid format.

Resolution: Include a valid Bearer token: Authorization: Bearer dlr_your_api_key

INVALID_API_KEY401

The provided API key is invalid

The API key does not exist or has never been valid.

Resolution: Verify the API key is correct and was copied in full.

EXPIRED_API_KEY401

The provided API key has expired

The API key had an expiration date that has passed.

Resolution: Create a new API key or update the expiration date.

REVOKED_API_KEY401

The provided API key has been revoked

The API key was manually revoked by the user.

Resolution: Create a new API key from the dashboard.

Permission Errors

FORBIDDEN403

You do not have permission to access this resource

The authenticated user cannot access this resource.

Resolution: Verify you own the resource or have been granted access.

BUSINESS_PLAN_REQUIRED403

API access requires a Business plan subscription

The current subscription does not include API access.

Resolution: Upgrade to the Business plan to enable API access.

INSUFFICIENT_PERMISSIONS403

Your API key does not have permission for this operation

The API key lacks the required read or write permission.

Resolution: Use an API key with appropriate permissions for this operation.

Request Errors

VALIDATION_ERROR400

Request validation failed

The request body or query parameters failed validation.

Resolution: Check the error details for specific field errors and fix them.

NOT_FOUND404

The requested resource was not found

The specified resource ID does not exist or was deleted.

Resolution: Verify the resource ID is correct and the resource exists.

CONFLICT409

The request conflicts with the current state

The operation would create a conflict (e.g., duplicate URL).

Resolution: Check for existing resources with the same unique properties.

Rate Limiting

RATE_LIMITED429

Rate limit exceeded. Please try again later

You have made too many requests in a short period.

Resolution: Wait for the Retry-After period and implement exponential backoff.

Server Errors

INTERNAL_ERROR500

An internal server error occurred

An unexpected error occurred on the server.

Resolution: Retry the request. If the error persists, contact support.

Handling Errors

Best practices for handling API errors in your application:

Error Handling Example

# The API returns errors in a consistent JSON format
curl https://deadlinkradar.com/api/v1/links/invalid-id \
  -H "Authorization: Bearer dlr_your_api_key"

# Returns:
# {
#   "error": {
#     "code": "NOT_FOUND",
#     "message": "The requested resource was not found",
#     "status": 404
#   }
# }

Validation Error Details

Validation errors include detailed field-level error information:

400Bad Request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "status": 400,
    "details": {
      "fields": {
        "url": [
          "URL is required"
        ],
        "check_frequency": [
          "Must be one of: hourly, daily, weekly, monthly"
        ],
        "group_id": [
          "Group not found"
        ]
      }
    }
  }
}

The details.fields object maps field names to arrays of error messages. Use this to display targeted feedback to users.

Rate Limits Endpoints