Skip to main content

​
Error Response Format

All Blnk API errors return a JSON response with an error field describing the issue: 
{
  "error": "Description of what went wrong"
}
Some endpoints may return additional error details: 
{
  "errors": "Detailed validation error message"
}
Or multiple errors: 
{
  "errors": [
    "Field 'currency' is required",
    "Field 'amount' must be greater than 0"
  ]
}

​
HTTP Status Codes

The Blnk API uses standard HTTP status codes to indicate the success or failure of requests.

​
Success Codes

​
200
success
OK - Request succeeded. The response body contains the requested data.
​
201
success
Created - Resource created successfully. The response body contains the new resource.
​
204
success
No Content - Request succeeded with no response body (typically for DELETE operations).

​
Client Error Codes

​
400
error
Bad Request - The request was malformed or contains invalid parameters.Common causes:
  • Missing required fields
  • Invalid JSON format
  • Field validation failures
  • Invalid query parameters
​
401
error
Unauthorized - Authentication failed or was not provided.Common causes:
  • Missing X-Blnk-Key header
  • Invalid or expired API key
  • Revoked API key
​
403
error
Forbidden - Valid authentication but insufficient permissions.Common causes:
  • API key lacks required scope for the resource
  • Attempting to access another owner’s resources
  • Missing required action permission (read/write/delete)
​
404
error
Not Found - The requested resource does not exist.Common causes:
  • Invalid resource ID
  • Resource has been deleted
  • Incorrect endpoint path
​
429
error
Too Many Requests - Rate limit exceeded.Solution: Reduce request frequency or contact support to increase limits.

​
Server Error Codes

​
500
error
Internal Server Error - An unexpected error occurred on the server.Action: Retry the request. If the error persists, contact support.

​
Common Error Scenarios

​
Authentication Errors

​
Missing Authentication

Status Code: 401 
{
  "error": "Authentication required. Use X-Blnk-Key header"
}
Solution: Add the X-Blnk-Key header with your API key or master key. 
curl -X GET http://localhost:5001/ledgers \
  -H "X-Blnk-Key: your-api-key"

​
Invalid API Key

Status Code: 401 
{
  "error": "Invalid API key"
}
Causes:
  • API key doesn’t exist in the database
  • API key format is incorrect
  • Typo in the key
Solution: Verify your API key is correct and hasn’t been revoked.

​
Expired API Key

Status Code: 401 
{
  "error": "API key is expired or revoked"
}
Solution: Create a new API key with a future expiration date.

​
Insufficient Permissions

Status Code: 403 
{
  "error": "Insufficient permissions for transactions:write"
}
Solution: Use an API key with the required scope or use the master key.

​
Validation Errors

​
Missing Required Field

Status Code: 400 
{
  "error": "Key: 'CreateLedger.name' Error:Field validation for 'name' failed on the 'required' tag"
}
Solution: Include all required fields in your request body.

​
Invalid Field Format

Status Code: 400 
{
  "errors": "invalid timestamp format. Please use ISO 8601 format (e.g., 2024-01-01T15:04:05Z)"
}
Solution: Ensure fields match the expected format (ISO 8601 for timestamps, valid JSON, etc.).

​
Invalid Query Parameter

Status Code: 400 
{
  "error": "Invalid limit value"
}
Causes:
  • Non-numeric value for numeric parameters
  • Negative values where positive required
  • Zero or negative limit/offset values
Solution: Use valid parameter values:
  • limit: Integer ≥ 1
  • offset: Integer ≥ 0

​
Resource Errors

​
Resource Not Found

Status Code: 404 
{
  "error": "API key not found"
}

{
  "error": "hook not found"
}
Solution: Verify the resource ID is correct and the resource exists.

​
Missing ID Parameter

Status Code: 400 
{
  "error": "id is required. Pass id in the route /:id"
}
Solution: Include the resource ID in the URL path: 
# Correct
GET /ledgers/ldg_1234567890

# Incorrect
GET /ledgers/

​
Unauthorized Resource Access

Status Code: 403 
{
  "error": "unauthorized"
}
Causes:
  • Attempting to access resources owned by another user
  • Missing owner query parameter
  • Owner parameter doesn’t match authenticated user
Solution: Include the correct owner parameter or use appropriate credentials.

​
Unknown Resource Type

Status Code: 403 
{
  "error": "Unknown resource type"
}
Cause: The API endpoint path doesn’t map to a known resource. Solution: Verify the endpoint URL is correct.

​
Error Codes by Endpoint

​
Ledger Endpoints

EndpointErrorStatusDescription
POST /ledgersValidation error400Missing or invalid name field
GET /ledgers/:idMissing ID400ID parameter not provided
GET /ledgersInvalid filters400Malformed filter parameters
PUT /ledgers/:idNot found400Ledger ID doesn’t exist

​
Balance Endpoints

EndpointErrorStatusDescription
POST /balancesMissing currency400currency field required
GET /balances/:idInvalid ID400Balance ID not provided
GET /balances/atInvalid timestamp400Timestamp format incorrect
PUT /balances/:id/identityMissing identity_id400identity_id field required

​
Transaction Endpoints

EndpointErrorStatusDescription
POST /transactionsValidation error400Missing required transaction fields
POST /transactionsInsufficient funds500Source balance too low
GET /transactions/:idNot found400Transaction doesn’t exist
POST /refund-transaction/:idAlready refunded400Transaction already refunded

​
API Key Endpoints

EndpointErrorStatusDescription
POST /api-keysValidation error400Missing name, owner, scopes, or expires_at
GET /api-keysUnauthorized401Missing owner query parameter
DELETE /api-keys/:idNot found404API key doesn’t exist
DELETE /api-keys/:idForbidden403Owner doesn’t match

​
Search Endpoints

EndpointErrorStatusDescription
POST /search/:collectionMissing collection400Collection parameter required
POST /search/:collectionInvalid query400Malformed search query
GET /search/reindexNot found404No reindex operation in progress

​
Reconciliation Endpoints

EndpointErrorStatusDescription
POST /reconciliation/uploadUpload failed500Failed to process file upload
POST /reconciliation/startStart failed500Failed to initiate reconciliation
GET /reconciliation/:idNot found404Reconciliation record doesn’t exist

​
Troubleshooting Guide

​
”Authentication required” Error

  1. Check if secure mode is enabled (BLNK_SERVER_SECURE=true)
  2. Ensure X-Blnk-Key header is included
  3. Verify the header name is correct (case-sensitive)
# Correct
curl -H "X-Blnk-Key: your-key" ...

# Incorrect
curl -H "x-blnk-key: your-key" ...
curl -H "Authorization: Bearer your-key" ...

​
“Invalid limit value” Error

  1. Ensure limit is a positive integer
  2. Check for typos in query parameters
  3. Use default values when uncertain
# Correct
GET /ledgers?limit=10&offset=0

# Incorrect
GET /ledgers?limit=-1
GET /ledgers?limit=abc

​
”Insufficient permissions” Error

  1. Check your API key’s scopes: 
    GET /api-keys?owner=your-owner
  2. Verify the required scope for the operation:
    • GET requests need resource:read
    • POST/PUT requests need resource:write
    • DELETE requests need resource:delete
  3. Use master key for full access during testing

​
”Unknown resource type” Error

  1. Verify the endpoint URL matches documented paths
  2. Check for typos in resource names
  3. Ensure resource is supported in your Blnk version
# Correct
POST /ledgers
GET /balance-monitors

# Incorrect (typo)
POST /ledger
GET /balance-monitor

​
”Entity not found” Error

  1. Confirm the resource ID exists: 
    GET /ledgers/:id
  2. Check for ID typos or incorrect prefixes
  3. Verify resource hasn’t been deleted

​
Rate Limit Exceeded

  1. Implement exponential backoff retry logic
  2. Reduce request frequency
  3. Check rate limit configuration: 
    BLNK_RATE_LIMIT_RPS=5000000
BLNK_RATE_LIMIT_BURST=10000000
  4. Contact support to increase limits if needed

​
Debugging Tips

​
Enable Detailed Logging

Check server logs for detailed error information: 
# View Blnk server logs
docker logs blnk-server

​
Validate JSON Payloads

Use a JSON validator before sending requests: 
# Validate JSON syntax
echo '{"name": "Test"}' | jq .

​
Test with cURL

Use verbose mode to see full request/response: 
curl -v -X POST http://localhost:5001/ledgers \
  -H "X-Blnk-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Test Ledger"}'

​
Check API Key Status

Verify your API key is valid and not expired: 
curl -X GET "http://localhost:5001/api-keys?owner=your-owner" \
  -H "X-Blnk-Key: your-master-key"

​
Best Practices

  1. Implement proper error handling: Catch and handle all error status codes in your application
  2. Log errors: Record error responses for debugging and monitoring
  3. Use retry logic: Implement exponential backoff for transient errors (500, 429)
  4. Validate before sending: Check request payloads locally before making API calls
  5. Monitor API health: Track error rates to identify issues early
  6. Keep credentials secure: Never log or expose API keys in error messages

​
Getting Help

If you encounter errors not covered in this guide:
  1. Check the GitHub Issues for similar problems
  2. Review server logs for detailed error traces
  3. Consult the specific endpoint documentation for requirements
  4. Open a new issue with:
    • Error message
    • Request details (endpoint, method, payload)
    • Expected vs actual behavior
    • Blnk version

Build docs developers (and LLMs) love

Get started for freeTalk to us