Errors

Seaavey API uses standard HTTP status codes. This page covers all possible error responses and how to handle them.

Error Format

All error responses follow this structure:

{
  "status": 400,
  "success": false,
  "message": "Human-readable error description"
}

Status Codes

Client Errors (4xx)

400 Bad Request

Missing or invalid parameters. Check the endpoint documentation for required fields.

401 Unauthorized

Missing, invalid, or expired API key. Check your x-api-key header.

403 Forbidden

Your account doesn't have permission to access this resource.

404 Not Found

The endpoint or resource doesn't exist. Check the URL path.

429 Too Many Requests

Rate limit exceeded. Wait and retry. See Rate Limits.

Server Errors (5xx)

500 Internal Server Error

Something went wrong on our end. Retry after a moment. If persistent, check system status.

502 Bad Gateway

Upstream service is unavailable. Usually temporary — retry in a few seconds.

503 Service Unavailable

Service is temporarily down for maintenance or overloaded.

Handling Errors

Recommended error handling pattern:

const response = await fetch(url, { headers });
const data = await response.json();

if (!response.ok) {
  switch (response.status) {
    case 401:
      // Refresh or replace API key
      break;
    case 429:
      // Wait and retry with exponential backoff
      const retryAfter = response.headers.get('Retry-After');
      await sleep(retryAfter ? parseInt(retryAfter) * 1000 : 5000);
      break;
    case 500:
      // Retry once, then report
      break;
    default:
      console.error(data.message);
  }
}

Common Mistakes

Forgetting the x-api-key header → 401
Sending an empty required parameter → 400
Using an invalid URL format for downloader endpoints → 400
Exceeding file size limits on upload endpoints → 400
Sending requests too fast without backoff → 429