API Errors

The Accomplish API uses conventional HTTP response codes to indicate the success or failure of an API request. In general: codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided, and codes in the 5xx range indicate an error with Accomplish's servers.

HTTP Status Code Summary

Code	Status	Description
200	OK	Everything worked as expected.
201	Created	The resource was created successfully.
400	Bad Request	The request was unacceptable, often due to missing a required parameter.
401	Unauthorized	No valid API key provided.
403	Forbidden	The API key doesn't have permissions to perform the request.
404	Not Found	The requested resource doesn't exist.
422	Unprocessable Entity	The parameters were valid but the request failed validation.
429	Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504	Server Errors	Something went wrong on Accomplish's end. (These are rare.)

Error Response Format

The Accomplish API returns errors in two different formats depending on the type of error:

General Errors

For most errors, the API returns a single error object:

{
  "error": {
    "message": "Invalid API key. Ensure your API key is properly encoded and valid.",
    "type": "authentication_error"
  }
}

Attributes:

• message - A human-readable message providing more details about the error
• type - The type of error returned (see error types below)

Validation Errors

For validation errors (HTTP 422), the API returns an array of specific field errors:

{
  "errors": [
    {
      "title": "Invalid value",
      "detail": "Missing field: name",
      "source": {
        "pointer": "/name"
      }
    },
    {
      "title": "Invalid value", 
      "detail": "String length is larger than maxLength",
      "source": {
        "pointer": "/description"
      }
    }
  ]
}

Attributes:

• title - The error category (typically "Invalid value")
• detail - A specific description of what went wrong
• source.pointer - JSON Pointer to the field that caused the error

Error Types

Authentication Errors (401)

Error Message	Cause
Missing API key. Please provide a valid API key as a Basic token.	No Authorization header provided
Invalid API key. Ensure your API key is properly encoded and valid.	API key is malformed or doesn't exist
Invalid authorization header format.	Authorization header is not properly formatted
Unsupported authentication scheme. Only Basic is supported.	Using authentication method other than Basic
Missing OAuth token.	OAuth endpoint called without token
Invalid or expired OAuth token.	OAuth token is invalid or has expired

Authorization Errors (403)

Error Message	Cause
Insufficient scope for this API key. Required: {scope}. Available: {scopes}	API key lacks required scope
You must be on a plan to access this resource.	Account doesn't have required subscription plan

Rate Limiting Errors (429)

{
  "error": "You have exceeded the rate limit of 500 requests per minute",
  "retry_after": 45
}

Response Headers:

• retry-after - Seconds to wait before retrying
• x-ratelimit-limit - Request limit (500 per minute)
• x-ratelimit-remaining - Remaining requests in current window
• x-ratelimit-reset - Unix timestamp when limit resets
• x-ratelimit-window - Window duration in seconds (60)

We recommend using exponential backoff when you receive rate limit errors.

Validation Errors (422)

Common validation error messages:

Detail Message	Field Issue
Missing field: {field}	Required field is not provided
Invalid value	Field value doesn't match expected format
String length is smaller than minLength	String is too short
String length is larger than maxLength	String is too long
Invalid enum value	Value not in allowed list
Duplicate value	Value already exists (e.g., unique constraint)
Value must be greater than {number}	Numeric value below minimum
Value must be less than {number}	Numeric value above maximum

Resource Errors (404)

{
  "error": {
    "message": "Could not find the requested resource",
    "type": "not_found_error"
  }
}

Server Errors (500+)

{
  "error": {
    "message": "Something went wrong. Please try again later.",
    "type": "internal_error"
  }
}

Server errors are rare and typically indicate a temporary issue with our systems.

Error Handling Best Practices

Retry Logic

• 4xx errors: Don't retry automatically - fix the request
• 429 errors: Use exponential backoff with retry-after header
• 5xx errors: Safe to retry with exponential backoff

Error Parsing

Always check the HTTP status code first, then parse the error response:

if (response.status >= 400) {
  const errorData = await response.json();
  
  if (errorData.errors) {
    // Handle validation errors
    errorData.errors.forEach(error => {
      console.log(`Field ${error.source.pointer}: ${error.detail}`);
    });
  } else if (errorData.error) {
    // Handle general errors
    console.log(`Error: ${errorData.error.message}`);
  }
}

Rate Limit Handling

if (response.status === 429) {
  const retryAfter = response.headers.get('retry-after');
  const delay = retryAfter ? parseInt(retryAfter) * 1000 : 1000;
  
  setTimeout(() => {
    // Retry the request
  }, delay);
}

Scope Error Handling

When you receive a 403 error due to insufficient scopes:

1. Check the error message for required vs. available scopes
2. Update your API key with the necessary scopes
3. Or use a different API key with appropriate permissions

Common Error Scenarios

Invalid API Key

curl -u invalid_key: https://accomplish.dev/api/v1/projects

{
  "error": {
    "message": "Invalid API key. Ensure your API key is properly encoded and valid.",
    "type": "authentication_error"
  }
}

Missing Required Field

curl -u sk_test_123: -X POST https://accomplish.dev/api/v1/projects \
  -d '{"description": "Missing name field"}'

{
  "errors": [
    {
      "title": "Invalid value",
      "detail": "Missing field: name", 
      "source": {
        "pointer": "/name"
      }
    }
  ]
}

Insufficient Scope

curl -u sk_readonly_123: -X POST https://accomplish.dev/api/v1/projects \
  -d '{"name": "New Project"}'

{
  "error": {
    "message": "Insufficient scope for this API key. Required: project:write. Available: project:read",
    "type": "authorization_error"
  }
}