Error Handling

Understand API error codes and how to handle them gracefully.

Overview

The API uses conventional HTTP response codes to indicate success or failure. Codes in the 2xx range indicate success, 4xx indicate client errors, and 5xx indicate server errors.

HTTP Status Codes

Code	Meaning
200	Success - Request completed successfully
201	Created - Resource was created successfully
400	Bad Request - Invalid request parameters
401	Unauthorised - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
422	Unprocessable - Validation failed
429	Too Many Requests - Rate limit exceeded
500	Server Error - Something went wrong on our end

Error Format

Error responses include a JSON body with details:

{
  "message": "The given data was invalid.",
  "errors": {
    "url": [
      "The url has already been taken."
    ]
  }
}

Common Errors

Invalid API Key

Returned when the API key is missing, malformed, or revoked.

401 Unauthorised

Resource Not Found

The requested resource (biolink, workspace, etc.) doesn't exist or you don't have access.

404 Not Found

Validation Failed

Request data failed validation. Check the errors object for specific fields.

422 Unprocessable Entity

Rate Limiting

API requests are rate limited to ensure fair usage. Rate limit headers are included in all responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1705320000

When rate limited, you'll receive a 429 response. Wait until the reset timestamp before retrying.

Tip: Implement exponential backoff in your retry logic. Start with a 1-second delay and double it with each retry, up to a maximum of 32 seconds.

← Webhooks API Reference →