API Errors

All API errors return a consistent JSON structure with an error code, message, and request ID for debugging. Use the error code to handle specific cases programmatically.

What It Is

The API uses standard HTTP status codes combined with a structured error response. Each error includes a machine-readable code and human-readable message.

Error Response Format

``json


{
"error": {
"code": "NOT_FOUND",
"message": "Project not found",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
}
}



Error Codes Reference

HTTP Status Error Code Meaning
400 VALIDATION_ERROR Invalid request body or parameters
401 UNAUTHORIZED Missing or invalid API key
403 FORBIDDEN API key lacks required scope
404 NOT_FOUND Resource not found
409 IDEMPOTENCY_CONFLICT Idempotency key reused with different body
429 RATE_LIMITED Rate limit exceeded
500 INTERNAL_ERROR Server error

Common Errors

UNAUTHORIZED (401)

Missing or invalid Authorization header.

HTTP Status	Error Code	Meaning
400	VALIDATION_ERROR	Invalid request body or parameters
401	UNAUTHORIZED	Missing or invalid API key
403	FORBIDDEN	API key lacks required scope
404	NOT_FOUND	Resource not found
409	IDEMPOTENCY_CONFLICT	Idempotency key reused with different body
429	RATE_LIMITED	Rate limit exceeded
500	INTERNAL_ERROR	Server error

json
{
"error": {
"code": "UNAUTHORIZED",
"message": "Missing or invalid Authorization header",
"requestId": "req_abc123"
}
}



Fix: Include a valid API key:

Authorization: Bearer sg_live_xxx



FORBIDDEN (403)

API key is valid but lacks required scope.

json
{
"error": {
"code": "FORBIDDEN",
"message": "API key lacks required scope: projects:write",
"requestId": "req_abc123"
}
}



Fix: Create a new key with the required scope or use a key with full permissions.

NOT_FOUND (404)

The requested resource doesn't exist or you don't have access.

json
{
"error": {
"code": "NOT_FOUND",
"message": "Project not found",
"requestId": "req_abc123"
}
}



Fix: Verify the resource ID and that it belongs to your account.

VALIDATION_ERROR (400)

Invalid request body or query parameters.

json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "name is required",
"requestId": "req_abc123"
}
}



Fix: Check request body against the API reference.

IDEMPOTENCY_CONFLICT (409)

Idempotency key was used with a different request body.

json
{
"error": {
"code": "IDEMPOTENCY_CONFLICT",
"message": "Idempotency key has already been used with a different request body",
"requestId": "req_abc123"
}
}



Fix: Use a unique idempotency key for each distinct request.

Error Handling Example

javascript
// JavaScript
async function apiRequest(endpoint, options) {

const response = await fetch(https://seogeo.tools/api/public/v1${endpoint}, {


...options,
headers: {
"Authorization": "Bearer sg_live_abc123",
"Content-Type": "application/json",
...options?.headers
}
});

const data = await response.json();

if (!response.ok) {
switch (data.error.code) {
case "RATE_LIMITED":
// Wait and retry
break;
case "UNAUTHORIZED":
// Re-authenticate
break;
default:

console.error(API Error [${data.error.requestId}]: ${data.error.message});


}
throw new Error(data.error.message);
}

return data;
}

FAQ

Q: How do I get more details about a 500 error?

A: Contact support with the requestId from the error response.

Q: Why do I get FORBIDDEN after creating a key?

A: Your key may not have the required scope. Check Settings > API Keys.

Q: Can I customize error messages?

A: No, but you can use the error code to display your own messages.