Making Requests
Send authenticated requests to the BrickHatch API, handle responses, and understand how the API is structured.
Overview
This guide explains how to authenticate, send requests to the BrickHatch API, and handle JSON responses.
It also covers how all responses are structured and how to safely work with them.
All API endpoints return JSON and use standard HTTP status codes. A 200 status means the request was successful.
Non-200 responses indicate an error and should be handled accordingly.
| Key | Value |
|---|---|
| Base URL | https://brickhatch.com/api/v1 |
| Content type | application/json |
| Authentication | Required via X-Api-Key header |
Authentication
Authentication is required for all API requests. This ensures that only authorized users and applications can access account or store data.
To authenticate, include your API key in the request headers via the X-Api-Key header.
If you have not created an API key yet:
Example request
JSON
{
"url": "https://api.brickhatch.com/endpoint",
"method": "GET",
"headers": {
"X-Api-Key": "your_api_key_here"
}
}
Sending requests
To interact with the API, send HTTP requests to the appropriate endpoint using standard methods.
HTTP methods
| Method | Description |
|---|---|
| GET | Retrieve data |
| POST | Create new resources |
| PUT | Update existing resources |
| DELETE | Remove resources |
All requests must include your API key and follow the expected structure for each endpoint.
Response structure
Every response follows one of two formats: a success response or an error response.
Success response
A successful operation returns a data object containing the requested or modified resource.
JSON
{
"requestId": "req_123456",
"data": {
// Response payload for the endpoint
}
}
| Field | Description |
|---|---|
| requestId | A unique identifier for the request, useful for debugging and support |
| data | The response payload for the endpoint |
Error response
If something goes wrong, the response will include an error object instead of data.
JSON
{
"requestId": "req_123456",
"error": {
"message": "BAD_REQUEST",
"humanMessage": "The request was invalid",
"field": "email",
"traceback": "..."
}
}
The error fields include:
| Field | Description |
|---|---|
| requestId | A unique identifier for the request |
| error.message | A machine-readable error type |
| error.humanMessage | A readable explanation of what went wrong |
| error.field | The specific field related to the error, if applicable |
| error.traceback | Internal debugging information |
Error types
Each error returns a specific message that indicates the type of error. The API can return the following error types:
| Error | Description |
|---|---|
| BAD_REQUEST | The request is malformed or missing required data |
| INVALID_FIELDS | One or more fields failed validation |
| UNAUTHORIZED | Authentication failed or API key is missing |
| EXPIRED_TOKEN | The API key or session is no longer valid |
| NOT_FOUND | The requested resource does not exist |
| RATE_LIMIT_EXCEEDED | Too many requests in a short period |
| UNVERIFIED | The account is not verified |
| INTERNAL_SERVER_ERROR | An unexpected server error occurred |
Handling responses
When working with the API, always validate the response before using the data.
- Check status code - Only treat the request as successful if the status code indicates success
- Check for errors - If the
errorproperty exists, handle it before continuing - Use data safely - Only access
datawhen no error is present - Log the request ID - Store request IDs for debugging and support
Troubleshooting failed requests
If your request is not working as expected:
- Check authentication - Ensure your API key is included and valid
- Validate input - Confirm all required fields are present and formatted correctly
- Inspect error message - Use
humanMessageto understand the issue - Share your request ID - Provide the
requestIdwhen contacting support
If issues continue, feel free to create a support ticket for further assistance.