Error Codes

Reference guide for API error codes, troubleshooting, and best practices.

Error Response Format

When an API request fails, you'll receive a JSON response with an error object containing details about what went wrong. The HTTP status code indicates the general category of the error.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ],
    "requestId": "req_abc123xyz"
  }
}

HTTP Status Codes

Code	Status	Description
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`400`	Bad Request	Invalid request parameters or body
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	API key lacks required permissions
`404`	Not Found	Resource does not exist
`409`	Conflict	Resource already exists or conflict in state
`422`	Unprocessable Entity	Request understood but cannot be processed
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Error	Server error - contact support

Error Codes Reference

The error.code field provides a machine-readable error identifier.

Authentication Errors

Code	Description
`UNAUTHORIZED`	No API key provided
`INVALID_API_KEY`	API key is invalid or revoked
`FORBIDDEN`	API key lacks permission for this action

Validation Errors

Code	Description
`VALIDATION_ERROR`	Request body or parameters are invalid
`MISSING_REQUIRED_FIELD`	A required field was not provided
`INVALID_FORMAT`	Field value has incorrect format
`OUT_OF_RANGE`	Value is outside allowed range

Resource Errors

Code	Description
`NOT_FOUND`	Requested resource does not exist
`ALREADY_EXISTS`	Resource with this identifier already exists
`CONFLICT`	Action conflicts with current resource state
`DELETED`	Resource has been deleted

Rate Limit Errors

Code	Description
`RATE_LIMITED`	Too many requests - slow down and retry

⚠️ Handling Rate Limits

When you receive a 429 error, check these response headers:

X-RateLimit-Limit - Total requests allowed per window
X-RateLimit-Remaining - Requests remaining in current window
X-RateLimit-Reset - Unix timestamp when the window resets
Retry-After - Seconds to wait before retrying

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please retry after 30 seconds.",
    "retryAfter": 30
  }
}

💡 Error Handling Best Practices

Always check the HTTP status code first - Use it to categorize the error type
Parse the error.code for programmatic handling - Don't rely on message text
Implement exponential backoff for retries - Start with 1s, double each retry, max 5 retries
Log the requestId - Include it when contacting support for faster debugging
Handle validation errors gracefully - Show field-level errors to users when possible

Example Error Responses

Validation Error (400)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format",
        "value": "not-an-email"
      },
      {
        "field": "startDate",
        "message": "Start date must be in the future"
      }
    ],
    "requestId": "req_abc123xyz"
  }
}

Not Found Error (404)

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Event not found",
    "resource": "event",
    "identifier": "non-existent-slug",
    "requestId": "req_def456xyz"
  }
}

Server Error (500)

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred. Please try again later.",
    "requestId": "req_ghi789xyz"
  }
}

🆘 Need Help?

If you're encountering persistent errors or unexpected behavior:

Include the requestId from the error response
Describe the expected vs actual behavior
Include the request method, URL, and (sanitized) body
Contact support@nookhive.com