Error Codes

Reference for all API error codes, their meanings, and how to handle them in your application.

Error Response Format

All API errors follow a consistent format:

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request body is missing required fields",
    "details": {
      "missingFields": ["name", "appStoreAppId"]
    }
  },
  "requestId": "req_abc123"
}

HTTP Status Codes

Status	Meaning
`200`	Success - Request completed successfully
`201`	Created - Resource created successfully
`400`	Bad Request - Invalid request body or parameters
`401`	Unauthorized - Missing or invalid API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource does not exist
`409`	Conflict - Resource already exists or conflict
`422`	Unprocessable Entity - Validation failed
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Something went wrong

Error Codes

Authentication Errors

Code	Description	Resolution
`MISSING_API_KEY`	No API key provided	Add Authorization header with Bearer token
`INVALID_API_KEY`	API key is invalid or revoked	Check your API key or create a new one
`EXPIRED_API_KEY`	API key has expired	Create a new API key

Request Errors

Code	Description	Resolution
`INVALID_REQUEST`	Request body is malformed	Check JSON syntax and required fields
`VALIDATION_ERROR`	Field validation failed	Check error details for invalid fields
`RESOURCE_NOT_FOUND`	Requested resource not found	Verify the resource ID exists

Rate Limiting Errors

Code	Description	Resolution
`RATE_LIMIT_EXCEEDED`	Too many requests	Wait and retry with exponential backoff
`QUOTA_EXCEEDED`	Monthly quota reached	Upgrade your plan or wait for reset

Store Errors

Code	Description	Resolution
`STORE_AUTH_FAILED`	Store credentials invalid	Update your store credentials
`STORE_APP_NOT_FOUND`	App not found in store	Verify the app ID and permissions
`STORE_SYNC_FAILED`	Failed to sync with store	Check store status and retry

Handling Errors

Here's an example of how to handle errors in your code:

async function makeRequest() {
  try {
    const response = await fetch('https://api.appstorecopilot.com/v1/projects', {
      headers: {
        'Authorization': `Bearer ${process.env.ASC_API_KEY}`
      }
    });

    if (!response.ok) {
      const error = await response.json();

      switch (error.error.code) {
        case 'RATE_LIMIT_EXCEEDED':
          // Wait and retry with exponential backoff
          const retryAfter = response.headers.get('Retry-After') || 60;
          await sleep(retryAfter * 1000);
          return makeRequest();

        case 'INVALID_API_KEY':
          throw new Error('Invalid API key. Please check your credentials.');

        case 'QUOTA_EXCEEDED':
          throw new Error('Monthly quota exceeded. Please upgrade your plan.');

        default:
          throw new Error(error.error.message);
      }
    }

    return response.json();
  } catch (error) {
    console.error('API Error:', error);
    throw error;
  }
}