Error Handling

Gigantics API endpoints return standard HTTP status codes and JSON error messages to help clients diagnose and handle issues.

HTTP Status Codes

Error Response Format

All error responses follow this simple JSON format:

{
  "message": "Error description"
}

The message field contains a human-readable description of what went wrong.

Common Error Scenarios

Missing API Key

Request:

curl "https://yourserver/api/org/proj/model/1/dataset/42"

Response:

{
  "message": "Not authorized"
}

Status: 403 Forbidden

Resolution: Include the API key via query parameter (?api_key=...) or Authorization header (Authorization: Bearer ...)

Invalid API Key

Request:

curl "https://yourserver/api/org/proj/model/1/dataset/42?api_key=invalid-key"

Response:

{
  "message": "Unknown API key"
}

Status: 403 Forbidden

Resolution: Verify the API key is correct and assigned to the endpoint

Inactive API Key

Response:

{
  "message": "Disabled API key"
}

Status: 403 Forbidden

Resolution: Activate the key in the UI or use a different active key

Unknown Endpoint

Response:

{
  "message": "Unknown API Endpoint"
}

Status: 403 Forbidden

Resolution: Verify the endpoint URI is correct and that an endpoint has been assigned to the resource

Resource Not Found

Request:

curl "https://yourserver/api/org/proj/model/1/dataset/99999?api_key=valid-key"

Response:

{
  "message": "Dataset not found"
}

Status: 404 Not Found

Resolution: Verify the dataset/pipeline ID exists and the URI path is correct

Wrong HTTP Method

Request:

curl -X POST "https://yourserver/api/org/proj/model/1/dataset/42?api_key=valid-key"

Response:

{
  "message": "Endpoint or method not allowed"
}

Status: 405 Method Not Allowed

Resolution: Use GET for dataset endpoints, POST for pipeline endpoints

Invalid Format Parameter

Request:

curl "https://yourserver/api/org/proj/model/1/dataset/42?api_key=valid-key&format=invalid"

Response:

{
  "message": "Unknown download format invalid, supported formats = json|sql|csv-zip|json-zip|oracle-loader"
}

Status: 500 Internal Server Error

Resolution: Use a valid format: sql, json, csv-zip, json-zip, or oracle-loader

Server Error

Response:

{
  "message": "Detailed error message from server"
}

Status: 500 Internal Server Error

Resolution: Check the error message for details. Retry with exponential backoff. If persistent, contact support.

Job Status Endpoint Errors

The job status endpoint (/api/job/:jobId) is publicly accessible (no authentication required) and returns:

Invalid Job ID

Response:

{
  "id": "invalid-id",
  "message": "Invalid job id"
}

Status: 404 Not Found

Job Not Found

Response:

{
  "job": "507f1f77bcf86cd799439011",
  "message": "Job is not available or has been deleted"
}

Status: 404 Not Found

Dataset Not Available (for dump jobs)

Response:

{
  "message": "Dataset is not available or has been deleted"
}

Status: 404 Not Found

Error Handling Best Practices

Retry Logic

1. Do retry:

   • 500 Internal Server Error - Temporary server issues
   • Network timeouts

2. Do NOT retry:

   • 403 Forbidden - Authentication issues won't resolve by retrying
   • 404 Not Found - Resource doesn't exist
   • 405 Method Not Allowed - Wrong method won't change

3. Conditional retry:

   • Check job status before retrying pipeline endpoints to avoid duplicate executions

Exponential Backoff

When retrying, use exponential backoff:

const delays = [1, 2, 4, 8, 16]; // seconds
for (let attempt = 0; attempt < delays.length; attempt++) {
  try {
    const response = await fetch(url);
    if (response.ok) break;
    if (response.status !== 500) break; // Don't retry non-5xx errors
  } catch (error) {
    if (attempt < delays.length - 1) {
      await sleep(delays[attempt] * 1000);
    }
  }
}

Logging

Log errors with context:

• Request URL
• Status code
• Error message
• Timestamp
• API key prefix (not full key)

Monitoring

Monitor for:

• Sudden increases in 403 errors (possible key compromise)
• Patterns of 404 errors (configuration issues)
• Frequent 500 errors (server issues)

Related Documentation

• API Endpoint Assignment - Learn how endpoints work
• Authentication - Understand API key authentication
• Multiple API Keys per Endpoint - Learn about key management