Errors

The Pulls API uses conventional HTTP status codes and returns structured error responses.

HTTP Status Codes

Code	Meaning
`200`	Success
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn’t exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Something went wrong

Error Response Format

All errors follow a consistent structure:

{
  "_tag": "ErrorType",
  "message": "Human-readable description",
  ...additional fields
}

The _tag field identifies the error type for programmatic handling.

Common Errors

Unauthorized

{
  "_tag": "Unauthorized",
  "message": "Invalid or missing API key"
}

Causes:

Missing Authorization header
Invalid API key
Revoked or expired key

Fix: Check your API key is valid and correctly formatted.

CardNotFound

{
  "_tag": "CardNotFound",
  "message": "Card not found",
  "cardId": "invalid-id-123"
}

Causes:

Card ID doesn’t exist
Typo in card ID
Card from unsupported TCG

Fix: Verify the card ID using the search endpoint first.

RateLimitExceeded

{
  "_tag": "RateLimitExceeded",
  "message": "Rate limit exceeded. Retry after 60 seconds.",
  "retryAfter": 60
}

Causes:

Exceeded daily request quota
Exceeded per-minute limit

Fix: Wait for the retryAfter period or upgrade your plan.

ValidationError

{
  "_tag": "ValidationError",
  "message": "Invalid request parameters",
  "errors": [
    {
      "path": ["query", "limit"],
      "message": "Expected number, got string"
    }
  ]
}

Causes:

Invalid parameter types
Missing required fields
Values out of range

Fix: Check the API reference for correct parameter types and constraints.

Handling Errors in Code

TypeScript

import { PullsAPI, CardNotFoundError } from '@pulls/sdk'

try {
  const card = await pulls.cards.get('sv7-001')
} catch (error) {
  if (error instanceof CardNotFoundError) {
    console.log(`Card ${error.cardId} not found`)
  } else {
    throw error
  }
}

Using Effect

import { Effect } from 'effect'
import { CardNotFoundError } from '@pulls/sdk'

const program = pulls.cards.get('sv7-001').pipe(
  Effect.catchTag('CardNotFound', (error) =>
    Effect.succeed({ fallback: true, cardId: error.cardId })
  )
)

Debugging

Include request IDs when contacting support:

X-Request-Id: req_abc123xyz

Every response includes this header for tracking.