Errors

Error Format

All errors follow the same format:

{
  "ok": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

Error Codes

Code	HTTP Status	Description
`INVALID_API_KEY`	401	Missing or invalid API key
`REVOKED_API_KEY`	401	API key has been revoked
`NO_CREDITS`	402	Insufficient balance for this request
`VALIDATION_ERROR`	400	Request body validation failed
`NOT_FOUND`	404	Endpoint or resource not found
`JOB_NOT_FOUND`	404	Media job not found
`JOB_EXPIRED`	410	Job result has expired, resubmit your request
`MEDIA_MODEL_NOT_FOUND`	400	Unknown media model ID
`UPSTREAM_ERROR`	502	Upstream provider returned an error
`AI_UPSTREAM_ERROR`	502	AI provider returned an error
`INTERNAL_ERROR`	500	Something went wrong on our end

Handling Errors

const res = await fetch('https://api.yepapi.com/v1/seo/keywords', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ keywords: ['nextjs seo'] }),
});

const result = await res.json();

if (!result.ok) {
  const { code, message } = result.error;

  if (code === 'NO_CREDITS') {
    // Add funds at https://yepapi.com/dashboard/billing
  }
}

Request IDs

Every response carries an x-request-id header and a top-level request_id field in the JSON body:

{
  "ok": false,
  "request_id": "3f1c9e2a-7b4d-4e8f-9a21-0c5d6e7f8a9b",
  "error": {
    "code": "UPSTREAM_ERROR",
    "message": "Upstream data source returned an error"
  }
}

You can look up any data API call — including failed ones (4xx/5xx, and 504 Gateway Timeout, shown with status 504) — under Dashboard → API Logs. It lists the request ID, endpoint, status code, cost and latency for your latest 100 data API calls. Failed calls are never charged.

Include the request ID when contacting support so we can find the exact call.

Upstream Errors

When an upstream data source returns an error, we return an UPSTREAM_ERROR with additional context:

{
  "ok": false,
  "error": {
    "code": "UPSTREAM_ERROR",
    "message": "Upstream data source returned an error",
    "upstream": {
      "status": 500,
      "message": "Internal server error"
    }
  }
}